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 自动拼接。典型取值：

部署形态	`NACOS_BASE_URL` 示例
1.x / 2.x 默认	`http://<host>:8848/nacos`
3.x 默认（无 contextPath）	`http://<host>:8080`
经网关转发到 `/nacos`	填网关对外完整地址

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"
      }
    }
  }
}

可用工具

工具	Nacos OpenAPI	类型	说明	只读模式
`nacos_get_config`	GET `/cs/config`	读	按 dataId + group + namespace 获取配置	✅
`nacos_publish_config`	POST `/cs/config`	写	发布 / 更新配置	❌
`nacos_delete_config`	DELETE `/cs/config`	写	删除配置（写前确认）	❌
`nacos_list_config_history`	GET `/cs/history/list`	读	配置历史列表（分页）	✅
`nacos_get_config_history`	GET `/cs/history`	读	指定 nid 历史详情	✅
`nacos_get_config_previous`	GET `/cs/history/previous`	读	配置上一版本	✅
`nacos_list_configs`	v1/v2: `GET /nacos/v1/cs/configs?search=blur`；v3: `GET /v3/console/cs/config/list`	读	命名空间下配置列表（dataId + group 等元数据，不含内容），支持过滤与分页。v1/v2 `search=blur` 不自动补通配符，模糊搜需显式 `关键词`	✅
`nacos_list_namespaces`	GET `/console/namespace/list`	读	查询所有命名空间	✅
`nacos_get_namespace`	GET `/console/namespace`	读	查询单个命名空间（v1 由列表过滤模拟）	✅
`nacos_create_namespace`	POST `/console/namespace`	写	创建命名空间	❌
`nacos_update_namespace`	PUT `/console/namespace`	写	编辑命名空间	❌
`nacos_delete_namespace`	DELETE `/console/namespace`	写	删除命名空间（写前确认）	❌

版本端点差异：

版本	路径前缀	备注
v1	`/v1`	若部署带 contextPath（如 `/nacos`），体现在 `NACOS_BASE_URL`
v2	`/v2`	同上
v3	`/v3/console`	命名空间路径带 `/core/` 段；accessToken 鉴权

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 传输与认证

变量	说明	默认值
`MCP_TRANSPORT`	传输协议：`stdio` / `sse` / `streamable-http`	`stdio`
`MCP_HOST`	HTTP 监听地址（stdio 忽略），默认仅本地回环；对外暴露需显式设置并务必配置 `MCP_AUTH_TOKEN`	`127.0.0.1`
`MCP_PORT`	HTTP 监听端口（stdio 忽略）	`8000`
`MCP_AUTH_TOKEN`	非空时启用 Bearer Token 认证	-（不鉴权）
`MCP_STATELESS_HTTP`	启用无状态 HTTP（适配 Serverless）	`false`
`MCP_LOG_LEVEL`	日志级别：`debug` / `info` / `warning` / `error`	`info`

Nacos 连接

变量	说明	默认值
`NACOS_BASE_URL`	必填。唯一地址参数，格式 `scheme://host[:port][/context-path]`；API 段按版本自动拼接	-
`NACOS_USERNAME`	用户名	-
`NACOS_PASSWORD`	密码	-
`NACOS_NAMESPACE`	默认命名空间 ID	`public`
`NACOS_VERSION`	Nacos 版本：`1` / `2` / `3`	`3`
`NACOS_READ_ONLY`	只读模式（禁用写工具）	`true`
`NACOS_INSECURE`	跳过 TLS 证书验证（自签名 / 内部 CA 场景）	`false`

只读模式（默认）

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

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

TLS 证书验证

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

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

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

多协议传输

协议	端点	适用
`stdio`（默认）	-	本地客户端集成（Claude Code、Cursor 等）
`sse`	`http://<host>:<port>/sse`	SSE 传输
`streamable-http`	`http://<host>:<port>/mcp`	远程部署 / 多客户端共享

启动示例：

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

URI	说明
`nacos://namespaces`	列出所有命名空间

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