The mcp-nacos server is an MCP server that enables AI assistants to query and manage Nacos configurations and namespaces, supporting versions 1.x, 2.x, and 3.x via multiple transport protocols.
Configuration Management:
Get configuration content by dataId, group, and namespace.
Publish (create/overwrite) configurations with support for yaml, json, properties, xml, text, toml, etc.
Delete configurations (destructive – triggers confirmation in supported clients).
List configuration metadata (dataId, group) with filtering and pagination.
Configuration History:
List paginated historical versions, including operator, operation type, and timestamp.
Get the full content of a specific historical version by nid.
Retrieve the content of the version immediately preceding the current one.
Namespace Management:
List all namespaces, including public, with quota and usage information.
Get details of a specific namespace (e.g., configuration count).
Create, update (name/description), and delete namespaces (destructive – triggers confirmation in supported clients).
Key Features:
Automatic API adaptation for Nacos v1, v2, and v3 based on configured NACOS_VERSION.
Read-only mode (NACOS_READ_ONLY=true) disables all write tools.
Transport options: stdio, SSE, streamable-http with optional Bearer token authentication.
Stateless HTTP mode suitable for serverless and multi-replica deployments.
Destructive operation confirmation (MRTR) for delete actions in compatible clients.
Exposes the MCP resource nacos://namespaces for read-only namespace metadata.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type @ followed by the MCP server name and your instructions, e.g., "@mcp-nacos get config dataId 'app.yaml' in group 'DEFAULT_GROUP'"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
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 公开镜像、或本地构建
Related MCP server: jewei-mcp-nacos
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 自动拼接。典型取值：
部署形态 |
|
1.x / 2.x 默认 |
|
3.x 默认（无 contextPath） |
|
经网关转发到 | 填网关对外完整地址 |
公开镜像：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 | 类型 | 说明 | 只读模式 |
| GET | 读 | 按 dataId + group + namespace 获取配置 | ✅ |
| POST | 写 | 发布 / 更新配置 | ❌ |
| DELETE | 写 | 删除配置（写前确认） | ❌ |
| GET | 读 | 配置历史列表（分页） | ✅ |
| GET | 读 | 指定 nid 历史详情 | ✅ |
| GET | 读 | 配置上一版本 | ✅ |
| v1/v2: | 读 | 命名空间下配置列表（dataId + group 等元数据，不含内容），支持过滤与分页。v1/v2 | ✅ |
| GET | 读 | 查询所有命名空间 | ✅ |
| GET | 读 | 查询单个命名空间（v1 由列表过滤模拟） | ✅ |
| POST | 写 | 创建命名空间 | ❌ |
| PUT | 写 | 编辑命名空间 | ❌ |
| DELETE | 写 | 删除命名空间（写前确认） | ❌ |
版本端点差异：
版本 | 路径前缀 | 备注 |
v1 |
| 若部署带 contextPath（如 |
v2 |
| 同上 |
v3 |
| 命名空间路径带 |
v3 创建命名空间字段为 customNamespaceId（同 v1），编辑/删除用 namespaceId。
只读模式（默认）：NACOS_READ_ONLY 默认 true，写工具不注册，Agent 看不到也调不到；设为 false 开启写工具。
写前确认：所有写操作通过 MCP 原生 Elicitation 二次确认；stdio 等不支持 Elicitation 的客户端，SDK 直接返回 -32021 拒绝执行（fail-closed）。
配置唯一键三元组：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 传输与认证
变量 | 说明 | 默认值 |
| 传输协议： |
|
| HTTP 监听地址（stdio 忽略），默认仅本地回环；对外暴露需显式设置并务必配置 |
|
| HTTP 监听端口（stdio 忽略） |
|
| 非空时启用 Bearer Token 认证 | -（不鉴权） |
| 启用无状态 HTTP（适配 Serverless） |
|
| 日志级别： |
|
Nacos 连接
变量 | 说明 | 默认值 |
| 必填。唯一地址参数，格式 | - |
| 用户名 | - |
| 密码 | - |
| 默认命名空间 ID |
|
| Nacos 版本： |
|
| 只读模式（禁用写工具） |
|
| 跳过 TLS 证书验证（自签名 / 内部 CA 场景） |
|
默认只读，写工具不注册。需写操作时显式关闭：
{ "env": { "NACOS_READ_ONLY": "false" } }默认验证 TLS 证书（行为与 httpx 一致）。自签名或内部 CA 环境：
{ "env": { "NACOS_INSECURE": "true" } }禁用证书验证不安全，生产环境应使用受信任 CA 签发的有效证书。
协议 | 端点 | 适用 |
| - | 本地客户端集成（Claude Code、Cursor 等） |
|
| SSE 传输 |
|
| 远程部署 / 多客户端共享 |
启动示例：
MCP_TRANSPORT=streamable-http \
MCP_HOST=0.0.0.0 MCP_PORT=8000 \
MCP_AUTH_TOKEN=your-strong-token \
mcp-nacosMCP_AUTH_TOKEN 非空时，HTTP 请求需携带：
Authorization: Bearer <MCP_AUTH_TOKEN>兼容 X-Auth-Token / X-MCP-Token 请求头。GET /health 免鉴权（容器探活）。
stdio不经过网络，不做 Token 认证。未设MCP_AUTH_TOKEN时 HTTP 接口不鉴权，生产环境务必配置。
URI | 说明 |
| 列出所有命名空间 |
MCP_STATELESS_HTTP=true：每次请求独立处理，不保留会话状态。适配 Serverless（AWS Lambda、阿里云函数计算）或多副本部署。
MCP_TRANSPORT=streamable-http \
MCP_STATELESS_HTTP=true \
MCP_PORT=8000 \
mcp-nacosStateless 模式不支持 SSE 流式响应，每个 HTTP 请求独立完成后返回。
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:latestcp .env.example .env # 按需修改
docker compose up -ddocker-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 会回复该操作不可用，引导用户关闭只读模式或手动处理。
MIT
获取 Nacos 配置内容。
对应 Nacos OpenAPI：
v1：GET /nacos/v1/cs/configs（参数 tenant）
v2：GET /nacos/v2/cs/config（参数 namespaceId）
v3：GET /v3/console/cs/config（Console API，端口 8080）
按 dataId + group + namespace 唯一定位配置，返回配置内容。
Inputs: data_id (required), group_name, namespace_id, response_format. Returns: nacos_get_config 结构化输出模型。 包含配置的完整信息：dataId、group、namespace、内容、类型与 MD5。 所有字段均为 O…
查询某次历史变更记录。
对应 Nacos OpenAPI：
v1：GET /nacos/v1/cs/history
v2：GET /nacos/v2/cs/history
v3：GET /v3/console/cs/history（Console API）
按历史记录 ID（nid）返回该次变更的完整配置内容。
Inputs: nid (required), data_id (required), group_name, namespace_id. Returns: nacos_get_config_history 结构化输出模型
查询配置最新状态的前一次变更历史。
对应 Nacos OpenAPI：
v1：GET /nacos/v1/cs/history/previous
v2：GET /nacos/v2/cs/history/previous
v3：GET /v3/console/cs/history/previous（Console API）
按配置存储 ID（id）返回上一版本的完整配置内容。
Inputs: data_id (required), config_id (required), group_name, namespace_id. Returns: nacos_get_config_previous 结构化输出模型
查询单个命名空间详情。
对应 Nacos OpenAPI：
v1：官方无单查接口，由命名空间列表过滤模拟
v2：GET {base_url}/v2/console/namespace
v3：GET {base_url}/v3/console/core/namespace（Console API）
按 namespace_id 返回该命名空间的配额、使用量等详情。public 命名空间已自动归一化 （传 'public' 或空串都可查到，底层统一用空串 ""，三版本行为一致）。
Inputs: namespace_id (required). Returns: nacos_get_namespace 结构化输出模型
查询配置历史版本列表。
对应 Nacos OpenAPI：
v1：GET /nacos/v1/cs/history
v2：GET /nacos/v2/cs/history/list
v3：GET /v3/console/cs/history/list（Console API）
返回分页的历史版本列表（id、opType、操作人、时间等）。
Inputs: data_id (required), page_no, page_size, group_name, +1 more. Returns: nacos_list_config_history 结构化输出模型。 包含配置历史版本的分页信息与历史条目列表。 字段使用 camelCase 别名以直接匹配…
查询命名空间下的配置列表。
对应 Nacos OpenAPI：
v1 / v2：GET /nacos/v1/cs/configs?search=blur（搜索配置接口，Nacos 1.x/2.x 服务端均支持）
v3：GET /v3/console/cs/config/list（Console API 真列表端点，返回 Page） 三版本均支持 dataId/group/appName/config_tags 过滤 + pageNo/pageSize 分页，能力已对齐。
匹配语义（本地 1.x/2.x/3.x 实测一致）：search=blur 不会自动为 dataId/group 补通配符， 传子串不命中；需模糊匹配时显式传 '关键词'。传完整 dataId 精确命中一条。
返回该命名空间下配置的 data_id + group_name 等元数据列表（不含配置内容），并附 total 总数。
Inputs: search, data_id, page_no, app_name, +4 more. Returns: nacos_list_configs 结构化输出模型。 包含目标命名空间下配置的元数据列表（data_id / group_name / namespace_…
查询命名空间列表。
对应 Nacos OpenAPI：
v1：GET /nacos/v1/console/namespaces
v2：GET /nacos/v2/console/namespace/list
v3：GET /v3/console/core/namespace/list（Console API）
返回当前 Nacos 实例下的所有命名空间（含 public，及每个命名空间的配额与使用量）。
Inputs: no named parameters. Returns: nacos_list_namespaces 结构化输出模型。 包含当前 Nacos 实例下所有命名空间的列表。
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
Scored across 7 tools
Most tools target distinct resource+action pairs (e.g., list vs get namespace, get config vs list configs). However, the three history-related tools (list_config_history, get_config_history, get_config_previous) are closely related and could confuse agents, especially regarding which ID to use, though descriptions provide some clarity.
All tool names follow a consistent 'nacos_<verb>_<noun>' pattern with verbs limited to list and get. The naming is predictable, snake_case throughout, and clearly indicates each tool's purpose.
With 7 tools, the server is well-scoped for a Nacos configuration management interface. Each tool covers a necessary read or history operation, and the count is within the typical 3-15 range.
The tool set covers namespace and config read operations, including list/get and config history, but lacks any write operations such as create, update, or delete config. This is a notable gap for a tool named 'mcp-nacos' and will cause agent failures if configuration changes are attempted.
Manage ConfigDirector feature flags, remote configs, and targeting rules from AI assistants.
Enables AI assistants to retrieve event data and execute event management operations in Nunify.
AI agent registry — search, discover, register, and connect agents via MCP.
Unified API to query AWS, GCP, Azure and generate Terraform/CLI execution kits for AI agents.
