mcp-nacos

Nacos MCP Server —— 让 AI 助手查询与管理 Nacos 配置。

支持 Nacos 1.x / 2.x / 3.x，按 NACOS_VERSION 自动适配。

特性

• 多协议传输：stdio（默认）、sse、streamable-http
• HTTP 接口认证：Bearer Token 保护，未授权请求返回 401
• 写前确认：所有写操作通过 MCP 原生 Elicitation（Resolve + Elicit）二次确认，客户端不支持时 fail-closed 拒绝执行
• MCP Resources：nacos:// URI 暴露命名空间等只读元数据
• Stateless HTTP：无会话状态，适配 Serverless / 多副本部署
• 灵活部署：uvx 免安装、Docker 公开镜像、或本地构建

快速开始

MCP 客户端（stdio，本地）

Claude Code 示例，写入项目 .mcp.json 或全局 ~/.claude.json：

{
  "mcpServers": {
    "nacos": {
      "type": "stdio",
      "command": "uvx",
      "args": ["mcp-nacos"],
      "env": {
        "NACOS_BASE_URL": "http://localhost:8848",
        "NACOS_USERNAME": "nacos",
        "NACOS_PASSWORD": "your-password",
        "NACOS_NAMESPACE": "dev",
        "NACOS_VERSION": "3",
        "NACOS_READ_ONLY": "false"
      }
    }
  }
}

Cursor / OpenCode / Claude Desktop 等客户端格式相同：command: uvx + args: ["mcp-nacos"] + NACOS_* 环境变量。

NACOS_BASE_URL 格式（唯一地址参数，三版本通用）： scheme://host[:port][/context-path]。端口缺省按协议默认；是否带 /nacos 或反向代理前缀由部署决定，API 段（/v1/cs/configs、/v2/cs/config、/v3/console/cs/config 等）按 NACOS_VERSION 自动拼接。典型取值：

Docker（公开镜像，免构建）

公开镜像：ghcr.io/zhouweico/mcp-nacos:latest。

方式一：stdio（客户端拉起容器）

{
  "mcpServers": {
    "nacos": {
      "type": "stdio",
      "command": "docker",
      "args": ["run", "-i", "--rm", "ghcr.io/zhouweico/mcp-nacos:latest"],
      "env": {
        "NACOS_BASE_URL": "http://your-nacos-host:8080",
        "NACOS_USERNAME": "nacos",
        "NACOS_PASSWORD": "your-password",
        "NACOS_NAMESPACE": "dev",
        "NACOS_VERSION": "3"
      }
    }
  }
}

必须带 -i（保持 stdin 管道）。

方式二：HTTP + 认证（容器独立运行）

容器启动时会校验 NACOS_BASE_URL（缺失则 ${VAR:?...} 报错退出），必须显式传入。

启动容器：

docker run -d -p 8000:8000 \
  -e MCP_TRANSPORT=streamable-http \
  -e MCP_AUTH_TOKEN=your-strong-token \
  -e NACOS_BASE_URL=http://your-nacos-host:8848 \
  -e NACOS_VERSION=3 \
  ghcr.io/zhouweico/mcp-nacos:latest

客户端 .mcp.json：

{
  "mcpServers": {
    "nacos": {
      "type": "streamable-http",
      "url": "http://localhost:8000/mcp",
      "headers": {
        "Authorization": "Bearer your-strong-token"
      }
    }
  }
}

可用工具

版本端点差异：

v3 创建命名空间字段为 customNamespaceId（同 v1），编辑/删除用 namespaceId。

只读模式（默认）：NACOS_READ_ONLY 默认 true，写工具不注册，Agent 看不到也调不到；设为 false 开启写工具。

写前确认：所有写操作通过 MCP 原生 Elicitation 二次确认；stdio 等不支持 Elicitation 的客户端，SDK 直接返回 -32021 拒绝执行（fail-closed）。

Nacos 概念

配置唯一键三元组：namespace → group → dataId。

• namespace：隔离多环境 / 多租户（dev / test / prod）。未指定时用 NACOS_NAMESPACE，默认 public。
• group：同命名空间下的逻辑分组，默认 DEFAULT_GROUP。
• dataId：配置项唯一标识（通常对应文件名）。
• type：yaml / json / properties / text / xml / toml 等，发布时通过 config_type 指定。

版本字段差异：1.x 用 tenant 作命名空间 ID，2.x/3.x 为 namespaceId，3.x 创建命名空间又回到 customNamespaceId。本 Server 已按版本适配，调用方统一传 namespace_id 即可。

配置

环境变量

MCP 传输与认证

Nacos 连接

只读模式（默认）

默认只读，写工具不注册。需写操作时显式关闭：

{ "env": { "NACOS_READ_ONLY": "false" } }

TLS 证书验证

默认验证 TLS 证书（行为与 httpx 一致）。自签名或内部 CA 环境：

{ "env": { "NACOS_INSECURE": "true" } }

禁用证书验证不安全，生产环境应使用受信任 CA 签发的有效证书。

多协议传输

启动示例：

MCP_TRANSPORT=streamable-http \
MCP_HOST=0.0.0.0 MCP_PORT=8000 \
MCP_AUTH_TOKEN=your-strong-token \
mcp-nacos

接口认证

MCP_AUTH_TOKEN 非空时，HTTP 请求需携带：

Authorization: Bearer <MCP_AUTH_TOKEN>

兼容 X-Auth-Token / X-MCP-Token 请求头。GET /health 免鉴权（容器探活）。

stdio 不经过网络，不做 Token 认证。未设 MCP_AUTH_TOKEN 时 HTTP 接口不鉴权，生产环境务必配置。

MCP Resources

Stateless HTTP 模式

MCP_STATELESS_HTTP=true：每次请求独立处理，不保留会话状态。适配 Serverless（AWS Lambda、阿里云函数计算）或多副本部署。

MCP_TRANSPORT=streamable-http \
MCP_STATELESS_HTTP=true \
MCP_PORT=8000 \
mcp-nacos

Stateless 模式不支持 SSE 流式响应，每个 HTTP 请求独立完成后返回。

容器化部署

本地构建（Docker）

docker build -t mcp-nacos:latest .

docker run -d --name mcp-nacos -p 8000:8000 \
  -e MCP_TRANSPORT=streamable-http \
  -e MCP_AUTH_TOKEN=your-strong-token \
  -e NACOS_BASE_URL=http://your-nacos-host:8080 \
  -e NACOS_USERNAME=nacos \
  -e NACOS_PASSWORD=your-password \
  -e NACOS_NAMESPACE=public \
  -e NACOS_VERSION=3 \
  mcp-nacos:latest

Docker Compose

cp .env.example .env   # 按需修改
docker compose up -d

docker-compose.yml 已内置：基于 Dockerfile 构建（标记为 mcp-nacos:latest）、/health 健康检查、非 root 用户运行。

跳过本地构建、直接拉取公开镜像：删除 build: 段，只保留 image: ghcr.io/zhouweico/mcp-nacos:latest。

使用示例

下面示例均为自然语言提示，AI 助手会自动映射到对应 MCP 工具。三元组默认值：namespace=NACOS_NAMESPACE、group=DEFAULT_GROUP、type=yaml。

配置查询

帮我获取 Nacos 中 dataId 为 "application.yaml" 的配置

查看 nacos 里 user-service.yml 的配置内容，namespace 是 dev

列出 dev 命名空间下所有的配置项（只看 dataId 和 group）

模糊搜索 dataId 包含 "redis" 的配置

查看 prod 命名空间里 application 的历史版本，第 1 页

看一下 nid=128 那次历史发布的详细内容

回滚准备：取 application.yaml 上一版本的内容给我看下

配置发布与删除

把下面这段配置发布到 Nacos，dataId 是 "redis.yaml"：
server:
  port: 6379

把这段 JSON 配置发布成 order-config.json，类型 json，namespace 用 prod
{"timeout": 3000}

更新 user-service 的配置，把数据库端口改成 3307

删除 dev 命名空间下 group=DEFAULT_GROUP、dataId=legacy.properties 的配置

所有写操作（发布 / 删除 / 命名空间增删改）均需 MCP 原生 Elicitation 二次确认；不支持 Elicitation 的客户端（如 stdio）由 SDK 直接返回 -32021 拒绝执行。

命名空间管理

列出 Nacos 里所有的命名空间

查看 dev 命名空间的详情

新建一个命名空间，id 为 order-prod，名称 "订单生产环境"

把 dev 命名空间改名为 "开发环境"

删除命名空间 order-prod

批量与组合操作

把 dev 命名空间下所有配置项的 dataId 和 group 列出来，挑出 redis 相关的给我看内容

对比 application.yaml 最近两次历史版本的内容差异

把 test 命名空间的 user-service.yaml 配置同步发布到 prod 命名空间

默认只读

默认 NACOS_READ_ONLY=true，写工具（发布 / 删除 / 命名空间增删改）不注册，AI 只能执行查询类操作：

只读模式下：帮我删除 dataId=legacy.properties 的配置

AI 会回复该操作不可用，引导用户关闭只读模式或手动处理。

License

MIT