What is Nats Mcp Server

nats-mcp-server is an MCP (Model Context Protocol) server that facilitates access to the NATS messaging system using the NATS CLI, enabling AI agents to interact with NATS messaging effectively.

Use cases

Use cases for nats-mcp-server include enabling real-time communication between AI agents, orchestrating microservices interactions, and facilitating event-driven architectures in cloud environments.

How to use

To use nats-mcp-server, install the NATS CLI on your system, then you can publish messages, subscribe to subjects, and utilize request-reply patterns through the command line interface.

Key features

Key features include advanced message publishing options (such as headers and templates), configurable subscriptions with timeouts and message counts, support for request-reply patterns with headers, full integration with the NATS CLI, and robust error handling.

Where to use

nats-mcp-server can be used in various fields including cloud-native applications, microservices architectures, and AI-driven systems that require efficient messaging and communication between components.

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:

1. Download the latest release from NATS CLI Releases
2. Extract the archive
3. 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

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

1. Fork the repository
2. Create your feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add some amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. 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