Nats Mcp

mcp-nats

用于集成 NATS 消息系统的 Model Context Protocol (MCP) 服务

此 MCP 服务已通过 MCP Review 认证。

概述

本项目为 NATS 提供 Model Context Protocol (MCP) 服务，使 AI 模型和应用能够通过标准化接口与 NATS 消息系统交互。它提供了一套全面的工具，用于与 NATS 服务交互，非常适合需要使用消息系统的 AI 驱动型应用。

什么是 MCP？

Model Context Protocol (MCP) 是一种开放协议，用于规范应用向大模型 (LLM) 提供上下文的方式。此服务实现了 MCP 规范，为大模型和 AI 应用提供 NATS 消息功能，使它们能够：

• 以标准化方式与 NATS 消息系统交互
• 安全地检查和监控 NATS 服务及流
• 通过安全接口执行只读操作
• 与其他兼容 MCP 的客户端和宿主集成

功能

• 服务管理（只读操作）
  • 列出和检查 NATS 服务
  • 服务健康监控和 ping
  • 获取服务信息
  • 测量往返时间 (RTT)
• 流操作（只读操作）
  • 查看和检查 NATS 流
  • 查询流状态和信息
  • 查看和获取消息
  • 检查主题
• 对象存储操作
  • 创建和管理对象存储存储桶
  • 向对象存储上传和下载文件
  • 列出存储桶及其内容
  • 删除对象和存储桶
  • 监视存储桶的变更
  • 封存存储桶以防止更新
• 键值操作
  • 创建和管理 KV 存储桶
  • 存储和检索键值对
  • 监视 KV 更新
  • 删除键和存储桶
• 发布操作
  • 向 NATS 主题发布消息
  • 支持不同的消息格式
  • 异步发布消息
• 账户操作
  • 查看账户信息和指标
  • 生成账户报告（连接和统计数据）
  • 创建和恢复账户备份
  • 检查已连接服务的 TLS 证书链
• 多账户支持
  • 同时处理多个 NATS 账户
  • 安全管理凭据
• MCP 集成
  • 实现 MCP 服务规范
  • 兼容 Claude Desktop 等 MCP 客户端
  • 用于与大模型交互的标准化工具定义
  • 支持 AI 与 NATS 进行安全的只读交互

要求

• Go 1.25 或更高版本
• NATS 服务（可通过 URL 访问）
• 用于身份验证的 NATS 凭据
• 兼容 MCP 的客户端（例如 Claude Desktop 或其他 MCP 客户端）

安装

使用 Go

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

从源代码构建

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

Helm chart（Kubernetes）

chart 位于 deploy/charts/mcp-nats。安装指南（包括 OCI / GHCR 和 umbrella chart 的 dependencies）、values 概览、探针以及 HashiCorp Vault Agent Injector 示例，请参阅 deploy/charts/mcp-nats/README.md。

从代码库根目录快速开始：

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

已发布的版本也可以从 OCI 安装，例如：

helm install mcp-nats oci://ghcr.io/sinadarbouy/charts/mcp-nats --version "0.1.4" --namespace mcp-nats --create-namespace

有关 Chart.yaml 依赖项片段和注册表登录，请参阅 chart README。

容器镜像签名

带标签的版本会推送 ghcr.io/sinadarbouy/mcp-nats，并使用 Sigstore Cosign 通过无密钥 GitHub OIDC 对多架构索引（以及每个平台的清单）进行签名。

验证已发布的标签：

cosign verify ghcr.io/sinadarbouy/mcp-nats:0.1.4 \
  --certificate-identity-regexp 'https://github.com/sinadarbouy/mcp-nats/.github/workflows/(release\.yml@refs/tags/v.*|sign-image\.yml@refs/heads/main)' \
  --certificate-oidc-issuer https://token.actions.githubusercontent.com

添加签名功能之前发布的历史标签，可从 Actions → sign-image（从 main 运行）进行签名。

Tilt 集成测试（Docker Desktop Kubernetes）

使用 Tilt 部署官方 NATS 和本地 mcp-nats chart，以进行端到端身份验证测试。

先决条件：

• 已安装 Tilt
• 已安装 Helm
• 已启用 Docker Desktop Kubernetes
• 当前 kube context 设置为 docker-desktop

启动集成环境：

tilt up

此操作会使用：

• Tiltfile
• deploy/tilt/nats-values.yaml
• deploy/tilt/mcp-nats-values.yaml
• 在 Helm 部署前，使用 deploy/tilt/Dockerfile.tilt 在本地构建镜像

停止并清理：

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

快速验证命令：

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

身份验证冒烟测试：

• NATS 在 deploy/tilt/nats-values.yaml 中配置了 mcpuser / mcppassword。
• mcp-nats 通过 deploy/tilt/mcp-nats-values.yaml 中由 chart 管理的密钥使用相同凭据。
• 如果凭据不匹配，mcp-nats 日志会显示连接/身份验证失败。

配置

环境变量

• NATS_URL：NATS 服务的 URL（例如，localhost:4222）
• NATS_<ACCOUNT>_CREDS：每个账户的 Base64 编码 NATS 凭据
  • 示例：NATS_SYS_CREDS、NATS_A_CREDS
• NATS_NO_AUTHENTICATION：设为 "true" 以启用匿名连接（无需凭据）
• NATS_USER：用于用户名/密码身份验证的用户名或令牌
• NATS_PASSWORD：用于用户名/密码身份验证的密码

命令行标志

• --transport：传输类型（stdio、sse 或 streamable-http），默认值：streamable-http
• --address：HTTP 传输的监听地址，默认值：0.0.0.0:8000
• --endpoint-path：streamable-http 传输的端点路径，默认值：/mcp
• --sse-address：--address 的弃用别名
• --log-level：日志级别（debug、info、warn、error），默认值：info
• --json-logs：以 JSON 格式输出日志，默认值：false
• --no-authentication：允许不使用凭据的匿名连接
• --user：NATS 用户名或令牌（也可通过 NATS_USER 环境变量设置）
• --password：NATS 密码（也可通过 NATS_PASSWORD 环境变量设置）

健康检查端点（HTTP 传输）

• GET /livez：进程存活检查（不验证 NATS 依赖项）
• GET /readyz：就绪检查（验证与 NATS_URL 的 TCP 连通性）
• GET /healthz：兼容性存活检查别名

使用 sse 或 streamable-http 传输运行时，可使用这些端点。

Helm chart 探针

默认探针和 lifecycle.preStop 的说明见 deploy/charts/mcp-nats/README.md。

身份验证方法

MCP NATS 服务支持三种身份验证方法：

1. 凭据身份验证（默认）：使用 NATS 凭据文件

   • 设置 NATS_<ACCOUNT>_CREDS 环境变量
   • 所有工具都需要 account_name 参数

2. 用户名/密码身份验证：使用用户名和密码

   • 设置 NATS_USER 和 NATS_PASSWORD 环境变量，或使用 --user 和 --password 标志

3. 匿名身份验证：无需身份验证

   • 设置 NATS_NO_AUTHENTICATION=true 环境变量，或使用 --no-authentication 标志

用法示例

# 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

将 VSCode 与远程 MCP 服务配合使用

确保你的 .vscode/settings.json 包含：

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

Cursor（mcpServers）：

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

匿名身份验证：

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

用户名/密码身份验证：

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

如果使用二进制文件：

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

使用二进制文件进行匿名身份验证：

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

使用二进制文件进行用户名/密码身份验证：

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

Docker 配置：

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

开发

先决条件

• Go 1.25+
• Docker（可选）
• NATS CLI
• 了解 MCP 规范

可用的 Make 命令

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

使用 stdio 传输进行测试

有关如何使用 stdio 传输测试 MCP 服务的详细说明，请参阅我们的 Stdio 示例指南。

资源

• Model Context Protocol 文档
• MCP 规范
• MCP 服务示例