> ## Documentation Index
> Fetch the complete documentation index at: https://docs.streamnative.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Local MCP Server

> Install and run the open-source StreamNative MCP Server on your machine to connect AI agents to StreamNative Cloud, Kafka, or Pulsar clusters.

The local StreamNative MCP Server (`snmcp`) is an open-source binary that runs on your machine and exposes StreamNative Cloud, Apache Kafka, and Apache Pulsar clusters as Model Context Protocol (MCP) tools. Your IDE copilot or agent runtime connects to the local server over stdio or SSE, and the server translates MCP tool calls into cluster operations.

Source code and Helm charts are available on [GitHub](https://github.com/streamnative/streamnative-mcp-server).

## Prerequisites

Before you install, make sure you have:

* **For StreamNative Cloud** — a StreamNative Cloud account, organization ID, and a [service account API key](/cloud/security/authentication/service-accounts/use-api-keys/api-keys-overview).
* **For external Kafka** — bootstrap server addresses and credentials (if authentication is enabled).
* **For external Pulsar** — the web service URL, service URL, and an authentication token (if required).

## Install

<Tabs>
  <Tab title="Homebrew (macOS / Linux)">
    ```bash theme={null}
    brew install streamnative/streamnative/snmcp
    ```

    Upgrade to the latest version:

    ```bash theme={null}
    brew upgrade snmcp
    ```
  </Tab>

  <Tab title="Docker">
    ```bash theme={null}
    docker pull streamnative/snmcp:latest
    ```

    Run with stdio (StreamNative Cloud example):

    ```bash theme={null}
    docker run --rm -i \
      -e SNMCP_ORGANIZATION=my-org \
      -e SNMCP_KEY_FILE=/keys/key.json \
      -v /path/to/key-file.json:/keys/key.json \
      streamnative/snmcp:latest \
      stdio
    ```

    Run with SSE:

    ```bash theme={null}
    docker run --rm -i -p 9090:9090 \
      -e SNMCP_ORGANIZATION=my-org \
      -e SNMCP_KEY_FILE=/keys/key.json \
      -v /path/to/key-file.json:/keys/key.json \
      streamnative/snmcp:latest \
      sse --http-addr :9090 --http-path /mcp
    ```
  </Tab>

  <Tab title="Build from source">
    Requires [Go 1.22+](https://go.dev/dl/):

    ```bash theme={null}
    git clone https://github.com/streamnative/streamnative-mcp-server.git
    cd streamnative-mcp-server
    make build
    ```

    The binary is created at `./bin/snmcp`.
  </Tab>
</Tabs>

## Quick start: connect to StreamNative Cloud

1. Create a service account and download the key file. See [Manage service accounts](/cloud/security/authentication/service-accounts/manage-service-accounts) for details.

2. Run the local server in stdio mode:

   ```bash theme={null}
   snmcp stdio --organization my-org --key-file /path/to/key-file.json
   ```

3. The server starts and waits for MCP requests on stdin/stdout. Point your IDE or agent runtime to this process (see [IDE integration](#ide-integration) below).

## Connect to an external Kafka cluster

Use the `--kafka-*` flags to connect to any Kafka cluster, including clusters outside StreamNative Cloud.

```bash theme={null}
snmcp stdio \
  --use-external-kafka \
  --kafka-bootstrap-servers broker1:9092,broker2:9092 \
  --kafka-auth-type SASL_SSL \
  --kafka-auth-mechanism PLAIN \
  --kafka-auth-user alice \
  --kafka-auth-pass "$KAFKA_PASSWORD" \
  --kafka-use-tls
```

**Additional Kafka flags:**

| Flag                                   | Description                                                |
| -------------------------------------- | ---------------------------------------------------------- |
| `--kafka-bootstrap-servers`            | Comma-separated list of broker addresses                   |
| `--kafka-auth-type`                    | Kafka auth type                                            |
| `--kafka-auth-mechanism`               | SASL mechanism (`PLAIN`, `SCRAM-SHA-256`, `SCRAM-SHA-512`) |
| `--kafka-auth-user`                    | SASL username                                              |
| `--kafka-auth-pass`                    | SASL password                                              |
| `--kafka-schema-registry-url`          | Schema Registry endpoint                                   |
| `--kafka-schema-registry-auth-user`    | Schema Registry auth username                              |
| `--kafka-schema-registry-auth-pass`    | Schema Registry auth password                              |
| `--kafka-schema-registry-bearer-token` | Schema Registry bearer token                               |
| `--kafka-use-tls`                      | Enable TLS for broker connections                          |
| `--kafka-client-key-file`              | Kafka mTLS client key file                                 |
| `--kafka-client-cert-file`             | Kafka mTLS client certificate file                         |
| `--kafka-ca-file`                      | Kafka CA certificate file                                  |

## Connect to an external Pulsar cluster

Use the `--pulsar-*` flags to connect to any Pulsar cluster.

```bash theme={null}
snmcp stdio \
  --use-external-pulsar \
  --pulsar-web-service-url http://localhost:8080 \
  --pulsar-service-url pulsar://localhost:6650 \
  --pulsar-token "$PULSAR_TOKEN"
```

**Additional Pulsar flags:**

| Flag                                        | Description                            |
| ------------------------------------------- | -------------------------------------- |
| `--pulsar-web-service-url`                  | Pulsar web service URL                 |
| `--pulsar-service-url`                      | Pulsar binary service URL              |
| `--pulsar-token`                            | Authentication token                   |
| `--pulsar-auth-plugin`                      | Pulsar auth plugin                     |
| `--pulsar-auth-params`                      | Pulsar auth parameters                 |
| `--pulsar-tls-allow-insecure-connection`    | Allow insecure TLS connections         |
| `--pulsar-tls-enable-hostname-verification` | Enable TLS hostname verification       |
| `--pulsar-tls-trust-certs-file-path`        | Path to trusted TLS certificate bundle |
| `--pulsar-tls-cert-file`                    | Client TLS certificate file            |
| `--pulsar-tls-key-file`                     | Client TLS key file                    |

> In external Kafka and external Pulsar modes, do not pass `--features`. The server enables the matching tool groups automatically.

## IDE integration

### Claude Desktop (stdio)

Add the following to your Claude Desktop MCP configuration file (`claude_desktop_config.json`):

```json theme={null}
{
  "mcpServers": {
    "streamnative": {
      "command": "snmcp",
      "args": [
        "stdio",
        "--organization", "${STREAMNATIVE_CLOUD_ORGANIZATION_ID}",
        "--key-file", "${STREAMNATIVE_CLOUD_KEY_FILE}",
        "--features", "all"
      ]
    }
  }
}
```

### Claude Code

Add the server using the Claude Code CLI:

```bash theme={null}
claude mcp add streamnative -- snmcp stdio --organization my-org --key-file /path/to/key-file.json --features all
```

### VS Code

Create or update `.vscode/mcp.json` in your workspace:

```json theme={null}
{
  "servers": {
    "streamnative": {
      "command": "snmcp",
      "args": [
        "stdio",
        "--organization", "${STREAMNATIVE_CLOUD_ORGANIZATION_ID}",
        "--key-file", "${STREAMNATIVE_CLOUD_KEY_FILE}",
        "--features", "all"
      ]
    }
  }
}
```

### Cursor

Add the following to your Cursor MCP configuration file (`.cursor/mcp.json`):

```json theme={null}
{
  "mcpServers": {
    "streamnative": {
      "command": "snmcp",
      "args": [
        "stdio",
        "--organization", "${STREAMNATIVE_CLOUD_ORGANIZATION_ID}",
        "--key-file", "${STREAMNATIVE_CLOUD_KEY_FILE}",
        "--features", "all"
      ]
    }
  }
}
```

## Feature control

Use the `--features` flag to select which tool groups are available. This controls token usage and limits the tool catalog to what you need.

```bash theme={null}
# Enable only Kafka admin and client tools (Cloud mode)
snmcp stdio --organization my-org --key-file /path/to/key-file.json --features kafka-admin,kafka-client

# Enable all Pulsar tools (Cloud mode)
snmcp stdio --organization my-org --key-file /path/to/key-file.json --features all-pulsar

# Enable everything (Cloud mode)
snmcp stdio --organization my-org --key-file /path/to/key-file.json --features all
```

See the [MCP Tools Reference](/agent-engine/sn-remote-mcp/remote-mcp-tools-reference) for the complete list of tool groups and their descriptions.

## SSE server mode

Run the local server as an SSE endpoint for multi-client setups:

```bash theme={null}
snmcp sse --http-addr :8080 --http-path /mcp --organization my-org --key-file /path/to/key-file.json --features all
```

Clients can connect to `http://localhost:8080/mcp/sse`.

Additional endpoints:

* Health check: `http://localhost:8080/mcp/healthz`
* Readiness check: `http://localhost:8080/mcp/readyz`

### Multi-session Pulsar mode (SSE only)

For external Pulsar, you can enable per-user session management on the SSE server:

```bash theme={null}
snmcp sse --http-addr :9090 --http-path /mcp \
  --use-external-pulsar \
  --pulsar-web-service-url http://pulsar.example.com:8080 \
  --pulsar-service-url pulsar://pulsar.example.com:6650 \
  --multi-session-pulsar \
  --session-cache-size 100 \
  --session-ttl-minutes 30
```

In this mode, requests to SSE and message endpoints must include `Authorization: Bearer <token>`.

## Read-only mode

Restrict the server to read-only operations:

```bash theme={null}
snmcp stdio --organization my-org --key-file /path/to/key-file.json --features all --read-only
```

In read-only mode, the server exposes only tools that inspect resources (list topics, peek messages, retrieve metrics) and blocks any operations that create, modify, or delete resources.

## Command logging

Enable command request and response logging for troubleshooting:

```bash theme={null}
snmcp stdio --organization my-org --key-file /path/to/key-file.json --features all \
  --enable-command-logging \
  --log-file /tmp/snmcp.log
```

## What's next

* Browse available tool groups in the [MCP Tools Reference](/agent-engine/sn-remote-mcp/remote-mcp-tools-reference).
* Compare with the managed [Remote MCP Server](/agent-engine/sn-remote-mcp/remote-mcp-overview) for a zero-install, team-shared alternative.
* Visit the [GitHub repository](https://github.com/streamnative/streamnative-mcp-server) for the latest releases, Helm charts, and contribution guidelines.