mcp-nats

A Model Context Protocol (MCP) server for NATS messaging system integration

This MCP server is certified by MCP Review.

Overview

This project provides a Model Context Protocol (MCP) server for NATS, enabling AI models and applications to interact with NATS messaging systems through a standardized interface. It exposes a comprehensive set of tools for interacting with NATS servers, making it ideal for AI-powered applications that need to work with messaging systems.

What is MCP?

The Model Context Protocol (MCP) is an open protocol that standardizes how applications provide context to Large Language Models (LLMs). This server implements the MCP specification to provide NATS messaging capabilities to LLMs and AI applications, allowing them to:

• Interact with NATS messaging systems in a standardized way
• Safely inspect and monitor NATS servers and streams
• Perform read-only operations through a secure interface
• Integrate with other MCP-compatible clients and hosts

Features

• Server Management (Read-only Operations)
  • List and inspect NATS servers
  • Server health monitoring and ping
  • Server information retrieval
  • Round-trip time (RTT) measurement
• Stream Operations (Read-only Operations)
  • View and inspect NATS streams
  • Stream state and information queries
  • Message viewing and retrieval
  • Subject inspection
• Object Store Operations
  • Create and manage object store buckets
  • Put and get files from object stores
  • List buckets and their contents
  • Delete objects and buckets
  • Watch buckets for changes
  • Seal buckets to prevent updates
• Key-Value Operations
  • Create and manage KV buckets
  • Store and retrieve key-value pairs
  • Watch for KV updates
  • Delete keys and buckets
• Publish Operations
  • Publish messages to NATS subjects
  • Support for different message formats
  • Asynchronous message publishing
• Account Operations
  • View account information and metrics
  • Generate account reports (connections and statistics)
  • Create and restore account backups
  • Inspect TLS chain for connected servers
• Multi-Account Support
  • Handle multiple NATS accounts simultaneously
  • Secure credential management
• MCP Integration
  • Implements MCP server specification
  • Compatible with MCP clients like Claude Desktop
  • Standardized tool definitions for LLM interaction
  • Safe, read-only operations for AI interaction with NATS

Requirements

• Go 1.25 or later
• NATS server (accessible via URL)
• NATS credentials for authentication
• MCP-compatible client (e.g., Claude Desktop, or other MCP clients)

Installation

Using Go

go install github.com/sinadarbouy/mcp-nats/cmd/mcp-nats@latest

Building from Source

git clone https://github.com/sinadarbouy/mcp-nats.git
cd mcp-nats
go build -o mcp-nats ./cmd/mcp-nats

Helm Chart (Kubernetes)

The Helm chart is available at deploy/charts/mcp-nats.

Install with defaults:

helm install mcp-nats ./deploy/charts/mcp-nats

Streamable HTTP mode with explicit server values:

helm install mcp-nats ./deploy/charts/mcp-nats \
  --set server.transport=streamable-http \
  --set server.address=0.0.0.0:8000 \
  --set server.endpointPath=/mcp

Anonymous authentication example:

helm install mcp-nats ./deploy/charts/mcp-nats \
  --set nats.url=nats://nats.default.svc:4222 \
  --set nats.noAuthentication=true

User/password authentication example with existing secret:

kubectl create secret generic mcp-nats-auth \
  --from-literal=NATS_USER=myuser \
  --from-literal=NATS_PASSWORD=mypass

helm install mcp-nats ./deploy/charts/mcp-nats \
  --set nats.url=nats://nats.default.svc:4222 \
  --set nats.noAuthentication=false \
  --set auth.existingSecret.name=mcp-nats-auth

Tilt Integration Test (Docker Desktop Kubernetes)

Use Tilt to deploy both official NATS and the local mcp-nats chart for end-to-end auth testing.

Prerequisites:

• Tilt installed
• Helm installed
• Docker Desktop Kubernetes enabled
• Current kube context set to docker-desktop

Start the integration stack:

tilt up

This uses:

• Tiltfile
• deploy/tilt/nats-values.yaml
• deploy/tilt/mcp-nats-values.yaml
• a local image build with deploy/tilt/Dockerfile.tilt before Helm deploy

Stop and clean up:

tilt down
helm uninstall -n mcp-nats-tilt nats mcp-nats
kubectl delete namespace mcp-nats-tilt --ignore-not-found

Quick verification commands:

kubectl get pods,svc -n mcp-nats-tilt
kubectl logs -n mcp-nats-tilt deploy/mcp-nats-mcp-nats
kubectl logs -n mcp-nats-tilt statefulset/nats
kubectl port-forward -n mcp-nats-tilt svc/mcp-nats-mcp-nats 8000:8000

Auth smoke test:

• NATS is configured with mcpuser / mcppassword in deploy/tilt/nats-values.yaml.
• mcp-nats uses the same credentials via chart-managed secret in deploy/tilt/mcp-nats-values.yaml.
• If credentials mismatch, mcp-nats logs will show connection/authentication failures.

Configuration

Environment Variables

• NATS_URL: The URL of your NATS server (e.g., localhost:4222)
• NATS_<ACCOUNT>_CREDS: Base64 encoded NATS credentials for each account
  • Example: NATS_SYS_CREDS, NATS_A_CREDS
• NATS_NO_AUTHENTICATION: Set to "true" to enable anonymous connections (no credentials required)
• NATS_USER: Username or token for user/password authentication
• NATS_PASSWORD: Password for user/password authentication

Command Line Flags

• --transport: Transport type (stdio, sse, or streamable-http), default: streamable-http
• --address: Address for HTTP transport to listen on, default: 0.0.0.0:8000
• --endpoint-path: Endpoint path for streamable-http transport, default: /mcp
• --sse-address: Deprecated alias of --address
• --log-level: Log level (debug, info, warn, error), default: info
• --json-logs: Output logs in JSON format, default: false
• --no-authentication: Allow anonymous connections without credentials
• --user: NATS username or token (can also be set via NATS_USER env var)
• --password: NATS password (can also be set via NATS_PASSWORD env var)

Health Endpoints (HTTP transports)

• GET /livez: process liveness check (does not validate NATS dependency)
• GET /readyz: readiness check (validates TCP connectivity to NATS_URL)
• GET /healthz: compatibility alias for liveness

These endpoints are available when running with sse or streamable-http transport.

Helm Probe Defaults

The chart now provides default probe and lifecycle settings tuned for safer rollouts:

• startupProbe -> /livez with extended startup window
• livenessProbe -> /livez
• readinessProbe -> /readyz
• lifecycle.preStop -> sleep 5 to help with endpoint drain before shutdown

Override any of these defaults with custom values:

helm upgrade --install mcp-nats ./deploy/charts/mcp-nats \
  --set readinessProbe.httpGet.path=/readyz \
  --set livenessProbe.httpGet.path=/livez \
  --set startupProbe.failureThreshold=18

Authentication Methods

The MCP NATS server supports three authentication methods:

1. Credentials-based Authentication (default): Uses NATS credentials files

   • Set NATS_<ACCOUNT>_CREDS environment variables
   • Requires account_name parameter in all tools

2. User/Password Authentication: Uses username and password

   • Set NATS_USER and NATS_PASSWORD environment variables or use --user and --password flags

3. Anonymous Authentication: No authentication required

   • Set NATS_NO_AUTHENTICATION=true environment variable or use --no-authentication flag

Example Usage

# Run with Streamable HTTP transport (default) and debug logging
./mcp-nats --log-level debug

# Run with custom Streamable HTTP endpoint path
./mcp-nats --transport streamable-http --address localhost:9000 --endpoint-path /mcp

# Run with JSON logging
./mcp-nats --json-logs

# Run with SSE transport
./mcp-nats --transport sse --address localhost:9000

# Run with anonymous authentication
./mcp-nats --no-authentication

# Run with user/password authentication
./mcp-nats --user myuser --password mypass

# Run with environment variables for authentication
NATS_NO_AUTHENTICATION=true ./mcp-nats
NATS_USER=myuser NATS_PASSWORD=mypass ./mcp-nats

Using VSCode with remote MCP server

Make sure your .vscode/settings.json includes:

"mcp": {
  "servers": {
    "nats": {
      "type": "streamable-http",
      "url": "http://localhost:8000/mcp"
    }
  }
}

or
cursor

{
  "mcpServers": {
    "nats": {
      "env": {
        "NATS_URL": "nats://localhost:42222",
        "NATS_SYS_CREDS": "<base64 of SYS account creds>"
        "NATS_A_CREDS": "<base64 of A account creds>"
      },
      "url": "http://localhost:8000/mcp"
    }
  }
}

Anonymous Authentication:

{
  "mcpServers": {
    "nats": {
      "env": {
        "NATS_URL": "nats://localhost:42222",
        "NATS_NO_AUTHENTICATION": "true"
      },
      "url": "http://localhost:8000/mcp"
    }
  }
}

User/Password Authentication:

{
  "mcpServers": {
    "nats": {
      "env": {
        "NATS_URL": "nats://localhost:42222",
        "NATS_USER": "myuser",
        "NATS_PASSWORD": "mypass"
      },
      "url": "http://localhost:8000/mcp"
    }
  }
}

If using the binary:

{
  "mcpServers": {
    "nats": {
      "command": "mcp-nats",
      "args": [
        "--transport",
        "stdio"
      ],
      "env": {
        "NATS_URL": "nats://localhost:42222",
        "NATS_SYS_CREDS": "<base64 of SYS account creds>",
        "NATS_A_CREDS": "<base64 of A account creds>"
      }
    }
  }
}

Anonymous Authentication with Binary:

{
  "mcpServers": {
    "nats": {
      "command": "mcp-nats",
      "args": [
        "--transport",
        "stdio",
        "--no-authentication"
      ],
      "env": {
        "NATS_URL": "nats://localhost:4222"
      }
    }
  }
}

User/Password Authentication with Binary:

{
  "mcpServers": {
    "nats": {
      "command": "mcp-nats",
      "args": [
        "--transport",
        "stdio",
        "--user",
        "myuser"
      ],
      "env": {
        "NATS_URL": "nats://localhost:4222",
        "NATS_PASSWORD": "mypass"
      }
    }
  }
}

Docker Configuration:

{
  "mcpServers": {
    "nats": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "--init",
        "-e",
        "NATS_URL",
        "-e",
        "NATS_SYS_CREDS",
        "cnadb/mcp-nats",
        "--transport",
        "stdio"
      ],
      "env": {
        "NATS_SYS_CREDS": "<base64 of SYS account creds>",
        "NATS_URL": "<nats url>"
      }
    }
  }
}

Development

Prerequisites

• Go 1.25+
• Docker (optional)
• NATS CLI
• Understanding of MCP specification

Available Make Commands

make help      # Print help message
make build     # Build the binary
make run       # Run in stdio mode
make run-sse   # Run with SSE transport
make lint      # Run linters

Testing with stdio Transport

For detailed instructions on how to test the MCP server using stdio transport, please refer to our Stdio Example Guide.

Resources

• Model Context Protocol Documentation
• MCP Specification
• Example MCP Servers