Local MCP Server - StreamNative Documentation

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.

Prerequisites

Before you install, make sure you have:

For StreamNative Cloud — a StreamNative Cloud account, organization ID, and a service account API key.
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

Homebrew (macOS / Linux)
Docker
Build from source

brew install streamnative/streamnative/snmcp

Upgrade to the latest version:

brew upgrade snmcp

docker pull streamnative/snmcp:latest

Run with stdio (StreamNative Cloud example):

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:

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

Requires Go 1.22+:

git clone https://github.com/streamnative/streamnative-mcp-server.git
cd streamnative-mcp-server
make build

The binary is created at ./bin/snmcp.

Quick start: connect to StreamNative Cloud

Create a service account and download the key file. See Manage service accounts for details.

Run the local server in stdio mode:

snmcp stdio --organization my-org --key-file /path/to/key-file.json

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

Connect to an external Kafka cluster

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

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.

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):

{
  "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:

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:

{
  "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):

{
  "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.

# 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 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:

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:

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:

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:

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.
Compare with the managed Remote MCP Server for a zero-install, team-shared alternative.
Visit the GitHub repository for the latest releases, Helm charts, and contribution guidelines.

StreamNative MCP Server

​Prerequisites

​Install

​Quick start: connect to StreamNative Cloud

​Connect to an external Kafka cluster

​Connect to an external Pulsar cluster

​IDE integration

​Claude Desktop (stdio)

​Claude Code

​VS Code

​Cursor

​Feature control

​SSE server mode

​Multi-session Pulsar mode (SSE only)

​Read-only mode

​Command logging

​What’s next