NATS

You run an MCP server that exposes NATS messaging capabilities to MCP clients. This server lets you publish, subscribe, and request via NATS with templates and headers, all through a simple MCP interface that wires into the NATS CLI.

How to use

Use an MCP client to interact with the NATS MCP Server. You will configure the client to connect to the local or remote MCP endpoint, then leverage the publish, subscribe, and request tools to work with NATS subjects. The server supports advanced publish options (headers, templates, reply subjects), configurable subscribe timeouts and counts, and a request–reply pattern with headers. The workflow is to start the MCP server, then issue commands from your MCP client that target the NATS subject you care about.

How to install

Prerequisites you need before installing the MCP server:

• Node.js 14 or newer

• NATS CLI (nats) to interact with NATS from the command line

Install NATS CLI on macOS

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

Install NATS CLI on Linux

snap install nats

Alternative Linux installation using APT

# 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

Install NATS CLI on Windows using Chocolatey or Scoop

choco install nats-io-client

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

Manual installation (NATS CLI) or building from source is also supported.

Install the MCP server from npm or build from source

# 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

Verifying the installation

# Check version
nats --version

# Test connection to default server
nats ping

# List available commands
nats help

Configuration and runtime setup

The MCP server is configured via environment variables. The key variable is NATS_URL, which points to the NATS server. If you do not set it, the server uses a default of nats://localhost:4222.

# Example of starting the MCP server with a local NATS endpoint
NATS_URL=nats://localhost:4222 node build/index.js

Security and reliability notes

The server includes robust error handling for connection issues, invalid parameters, timeouts, network problems, NATS-specific errors, and CLI execution failures. Ensure your NATS server is reachable and that the NATS_URL value matches your deployment.

Examples of use with MCP client tools

Publish a message to a subject with headers and optional templates, then subscribe to a subject to receive messages, or issue a request and await a reply. The MCP tools support headers, templates, and control over timing and counts.

Template functions and examples

When enabling templates, you can generate dynamic message content using functions like Count, TimeStamp, Unix, UnixNano, Time, ID, and Random(min, max). For example, publish a message that includes a random string.

Development and contributing

If you are contributing, you will typically install dependencies, build the project, and run the local server for testing. Build output appears in the build directory.

Error handling

Expect robust handling for connection failures, invalid parameters, timeouts, network errors, NATS-specific errors, and CLI execution issues. Resolve connectivity and permission problems as a priority when troubleshooting.

Notes

This MCP server exposes NATS through MCP tools such as publish, subscribe, and request, enabling practical messaging workflows in an MCP-enabled environment.

License

MIT license.

Available tools

publish

Publish a message to a NATS subject with optional headers, template processing, and a configurable count and delay.

subscribe

Subscribe to a NATS subject with optional timeout, message count, and an option to show raw payload.

request

Send a request to a NATS subject and wait for a reply, with optional headers and timeout.