README - NATS MCP Server by bmorphism

NATS MCP Server

An MCP (Model Context Protocol) server that provides access to NATS, a cloud native messaging system, through the NATS CLI.

Features

Publish messages with advanced options (headers, templates, reply subjects)
Subscribe to subjects with configurable timeouts and message counts
Request-reply pattern support with headers
Full NATS CLI integration
Error handling and cleanup

Requirements

Node.js >= 14.0.0
NATS CLI (nats)

Installing NATS CLI

macOS

Using Homebrew:

brew tap nats-io/nats-tools
brew install nats-io/nats-tools/nats

Linux

Using snap:

snap install nats

Using apt (Debian/Ubuntu):

# First, add the NATS repository
echo "deb https://dl.nats.io/nats-io/repo/deb nats release" | sudo tee /etc/apt/sources.list.d/nats.list
curl -fsSL https://dl.nats.io/nats-io/repo/deb/gpg.key | sudo gpg --dearmor -o /etc/apt/trusted.gpg.d/nats.gpg

# Then install
sudo apt-get update
sudo apt-get install nats-server

Using yum (RHEL/CentOS):

# Add the NATS repository
echo "[nats]
name=NATS Repository
baseurl=https://dl.nats.io/nats-io/repo/rpm/centos/\$releasever/\$basearch
gpgcheck=1
gpgkey=https://dl.nats.io/nats-io/repo/rpm/gpg.key
enabled=1" | sudo tee /etc/yum.repos.d/nats.repo

# Install
sudo yum install nats-server

Windows

Using Chocolatey:

choco install nats-io-client

Using Scoop:

scoop bucket add nats https://github.com/nats-io/scoop-bucket.git
scoop install nats

Manual installation:

Download the latest release from NATS CLI Releases
Extract the archive
Add the binary to your system PATH

Building from Source

If packages are not available for your system:

# Requires Go 1.16+
go install github.com/nats-io/natscli/nats@latest

Verifying Installation

After installation, verify the CLI works:

# Check version
nats --version

# Test connection to default server
nats ping

# List available commands
nats help

Installation

# Install from npm
npm install @modelcontextprotocol/nats-mcp-server

# Or clone and build from source
git clone https://github.com/bmorphism/nats-mcp-server.git
cd nats-mcp-server
npm install
npm run build

Configuration

The server can be configured using environment variables:

NATS_URL: NATS server URL (default: 'nats://localhost:4222')

Usage

The server provides the following MCP tools:

publish

Publish a message to a NATS subject with advanced options.

Parameters:

subject (required): NATS subject to publish to
message (required): Message to publish
reply (optional): Reply subject for request-reply patterns
headers (optional): Array of message headers (key-value pairs)
count (optional): Number of messages to publish
sleep (optional): Sleep duration between messages (e.g., "100ms")
template (optional): Enable Go template processing in message

Example with templates:

const result = await mcp.useTool("nats", "publish", {
  subject: "greetings",
  message: "Message {{Count}} @ {{Time}}",
  count: 5,
  sleep: "1s",
  template: true
});

Example with headers:

const result = await mcp.useTool("nats", "publish", {
  subject: "orders",
  message: "New order received",
  headers: [
    { key: "OrderId", value: "12345" },
    { key: "Priority", value: "high" }
  ]
});

Subscribe to a NATS subject and receive messages.

Parameters:

subject (required): NATS subject to subscribe to
timeout (optional): Subscription timeout in milliseconds (default: 5000)
count (optional): Number of messages to receive before exiting
raw (optional): Show only message payload

Example:

const result = await mcp.useTool("nats", "subscribe", {
  subject: "greetings",
  timeout: 10000,
  count: 5,
  raw: true
});

request

Send a request message and wait for a reply.

Parameters:

subject (required): NATS subject to send request to
message (required): Request message
timeout (optional): Request timeout in milliseconds (default: 5000)
headers (optional): Array of request headers (key-value pairs)

Example:

const result = await mcp.useTool("nats", "request", {
  subject: "service.time",
  message: "What time is it?",
  timeout: 3000,
  headers: [
    { key: "Locale", value: "en-US" }
  ]
});

Template Functions

When using templates (template: true), the following functions are available:

Count: Message number
TimeStamp: RFC3339 format current time
Unix: Seconds since 1970 in UTC
UnixNano: Nano seconds since 1970 in UTC
Time: Current time
ID: Unique ID
Random(min, max): Random string between min and max length

Example with random strings:

const result = await mcp.useTool("nats", "publish", {
  subject: "test",
  message: "Random data: {{ Random 10 100 }}",
  template: true
});

Adding to MCP Configuration

For Cline (VSCode Extension)

Add to ~/Library/Application Support/Code/User/globalStorage/saoudrizwan.claude-dev/settings/cline_mcp_settings.json:

{
  "mcpServers": {
    "nats": {
      "command": "node",
      "args": ["/path/to/nats-mcp-server/build/index.js"],
      "env": {
        "NATS_URL": "nats://localhost:4222"
      }
    }
  }
}

For Claude Desktop

Add to ~/Library/Application Support/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "nats": {
      "command": "node",
      "args": ["/path/to/nats-mcp-server/build/index.js"],
      "env": {
        "NATS_URL": "nats://localhost:4222"
      }
    }
  }
}

Error Handling

The server includes robust error handling for:

Connection failures
Invalid parameters
Timeouts
Network errors
NATS-specific errors
CLI execution errors

Development

To build the project:

npm run build

The build output will be in the build directory.

Contributing

Fork the repository
Create your feature branch (git checkout -b feature/amazing-feature)
Commit your changes (git commit -m 'Add some amazing feature')
Push to the branch (git push origin feature/amazing-feature)
Open a Pull Request

License

MIT

Acknowledgments

NATS.io - For the amazing messaging system
NATS CLI - For the CLI tool
Model Context Protocol - For the MCP framework