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 "Install 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: OssHub
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 唯一定位配置，返回配置内容。
| Name | Required | Description | Default |
|---|---|---|---|
| data_id | Yes | 配置 ID，如 'application.yaml'、'user-service.yml' | |
| group_name | No | 配置分组，默认 DEFAULT_GROUP | DEFAULT_GROUP |
| namespace_id | No | 命名空间 ID（如 dev/prod）；优先级：工具参数 > NACOS_NAMESPACE 环境变量 > 默认 public | |
| response_format | No | 输出格式：markdown 或 json | markdown |
| Name | Required | Description |
|---|---|---|
| md5 | No | |
| type | No | |
| content | No | |
| data_id | No | |
| group_name | No | |
| namespace_id | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint, idempotentHint, and destructiveHint, so safety is covered. The description adds value by mapping to Nacos OpenAPI v1/v2/v3 endpoints with different params, indicating the tool's internal implementation and that it returns config content. No contradictions exist.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise, front-loaded with the primary purpose, and uses each line effectively. It lists API versions and parameters without redundancy, earning every sentence's place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool is a simple retrieval operation with 4 parameters and an output schema (per signal), so the description need not detail return values. It covers the key uniqueness, API version mapping, and parameter precedence, making it complete for an agent to select and invoke correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, providing a baseline of 3. The description enriches parameter understanding by explaining the unique key combination and mapping v1 'tenant' to v2 'namespaceId', adding contextual meaning beyond the schema's labels and defaults.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool retrieves Nacos configuration content, with a specific verb '获取' and resource '配置内容'. It uniquely identifies a config by dataId, group, and namespace, which distinguishes it from sibling tools that list configs or retrieve history.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage when you want a specific config and know its dataId/group/namespace, but it does not explicitly mention alternatives or exclusions. No guidance is given on when to use this tool over sibling tools like nacos_list_configs or history tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
查询某次历史变更记录。
对应 Nacos OpenAPI：
v1：GET /nacos/v1/cs/history
v2：GET /nacos/v2/cs/history
v3：GET /v3/console/cs/history（Console API）
按历史记录 ID（nid）返回该次变更的完整配置内容。
| Name | Required | Description | Default |
|---|---|---|---|
| nid | Yes | 历史版本 ID（nid），必填 | |
| data_id | Yes | 配置 ID | |
| group_name | No | 配置分组，默认 DEFAULT_GROUP | DEFAULT_GROUP |
| namespace_id | No | 命名空间 ID，可选 |
| Name | Required | Description |
|---|---|---|
| id | No | |
| content | No | |
| data_id | No | |
| op_type | No | |
| operator | No | |
| group_name | No | |
| namespace_id | No | |
| publish_time | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and idempotentHint=true, so the safety profile is covered. The description adds the API endpoints and notes that it returns the complete config content, but does not discuss error behavior, auth needs, or rate limits. This is acceptable given the annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is brief and front-loaded with the purpose. The listing of three API versions adds some extra detail that may not be essential for an AI agent, but it is structured and not excessively long.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With an output schema present and clear annotations, the description sufficiently covers the tool's function and key parameter. It could mention prerequisites like the nid being valid, but the overall completeness is good for a simple read-only retrieval tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so all parameters are already well-documented. The description highlights nid as the key identifier, which aligns with the schema, but adds little beyond what the schema provides. Baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states that the tool queries a specific historical change record and returns the complete configuration content for a given nid. This is specific and distinguishes it from sibling tools like nacos_list_config_history (which lists records) and nacos_get_config_previous (which likely retrieves a previous version).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The context is clear: use this tool when you have a nid and need the full content of that historical version. However, it does not explicitly mention alternatives or when-not-to-use compared to similar tools, so it falls short of a 5.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
查询配置最新状态的前一次变更历史。
对应 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）返回上一版本的完整配置内容。
| Name | Required | Description | Default |
|---|---|---|---|
| data_id | Yes | 配置 ID | |
| config_id | Yes | 配置存储 ID（对应历史接口中的 id 字段），必填 | |
| group_name | No | 配置分组，默认 DEFAULT_GROUP | DEFAULT_GROUP |
| namespace_id | No | 命名空间 ID，可选 |
| Name | Required | Description |
|---|---|---|
| id | No | |
| content | No | |
| data_id | No | |
| op_type | No | |
| operator | No | |
| group_name | No | |
| namespace_id | No | |
| publish_time | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and idempotentHint=true. The description adds value by clarifying that it returns the complete config content of the previous version and that config_id corresponds to the id field in the history API. It also lists the three API endpoint variants, which is extra context beyond the annotations. No contradiction exists.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is short and front-loaded with the purpose, followed by a compact endpoint list and a behavior statement. The endpoint list might be slightly over-detailed for invocation, but it is not wasteful. Overall, it is concise and well-structured.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description covers the main purpose, output behavior, and parameter semantics, and an output schema exists for return values. It does not explicitly contrast with sibling history/lookup tools, but for a read-only query with strong annotations and schema coverage, it is sufficiently complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so baseline is 3. The description adds crucial clarification that config_id is '配置存储 ID（对应历史接口中的 id 字段）' and is required, reinforcing its role beyond the generic schema description. This extra semantic context justifies a 4.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose: '查询配置最新状态的前一次变更历史' (query the previous change history of the latest config state) and specifies that it returns the complete content of the previous version. This is specific and distinguishes it from siblings like nacos_get_config (current config) and nacos_get_config_history (specific history version).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage by describing what the tool does (retrieve last previous version), but it does not explicitly state when to use this over alternatives such as nacos_get_config_history or nacos_list_config_history. No when-not guidance or alternative tool references are provided.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
查询单个命名空间详情。
对应 Nacos OpenAPI：
v1：官方无单查接口，由命名空间列表过滤模拟
v2：GET {base_url}/v2/console/namespace
v3：GET {base_url}/v3/console/core/namespace（Console API）
按 namespace_id 返回该命名空间的配额、使用量等详情。public 命名空间已自动归一化 （传 'public' 或空串都可查到，底层统一用空串 ""，三版本行为一致）。
| Name | Required | Description | Default |
|---|---|---|---|
| namespace_id | Yes | 命名空间 ID。优先级：工具参数 > 环境变量 NACOS_NAMESPACE > 默认 public。查 public 传 'public' 或空串均可（工具会自动归一化：public 的真实 id 因版本而异，2.x 为空串，已统一处理） |
| Name | Required | Description |
|---|---|---|
| type | No | |
| quota | No | |
| namespace | No | |
| config_count | No | |
| namespace_show_name | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, openWorldHint=true, idempotentHint=true, and destructiveHint=false. The description adds valuable behavioral context about public namespace normalization across versions ('传 'public' 或空串都可查到，底层统一用空串') and version-specific endpoint behavior, which goes beyond the annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured with clear topic sentences and bullet-pointed version details. It is moderately concise, though it somewhat duplicates normalization info already in the schema. Overall, every sentence contributes to understanding.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool has a rich output schema and strong annotations. The description provides sufficient context for a single-parameter read operation, including version compatibility, normalization behavior, and return value summary. Missing edge-case behavior (e.g., not found) but not critical for a read-only tool with this simplicity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the baseline is 3. The tool description repeats normalization information already present in the schema's parameter description (priority, 'public' handling). It does not add new parameter semantics beyond what the schema already covers.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states '查询单个命名空间详情' (query single namespace details), which is a specific verb+resource action. It distinguishes from sibling 'nacos_list_namespaces' by focusing on a single namespace and mentions returning quota and usage details.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The context is clear: this tool is for retrieving a single namespace's details. It provides version-specific API notes (v1/v2/v3) and mentions that v1 uses a filtered list simulation, implicitly differentiating from the list tool. However, it lacks an explicit 'use this instead of list_namespaces' statement or exclusion criteria.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
查询配置历史版本列表。
对应 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、操作人、时间等）。
| Name | Required | Description | Default |
|---|---|---|---|
| data_id | Yes | 配置 ID | |
| page_no | No | 页码，默认 1 | |
| page_size | No | 每页条数，默认 100 | |
| group_name | No | 配置分组，默认 DEFAULT_GROUP | DEFAULT_GROUP |
| namespace_id | No | 命名空间 ID，可选 |
| Name | Required | Description |
|---|---|---|
| pageItems | No | |
| pageNumber | No | |
| totalCount | No | |
| pagesAvailable | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint, idempotentHint, and destructiveHint=false. The description adds value by listing the specific OpenAPI endpoints (v1, v2, v3) and the paginated response fields, providing behavioral context beyond the annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise and well-structured: a single-purpose opening sentence, a bullet list of endpoint mappings, and a final note on return content. It is front-loaded and every sentence earns its place without unnecessary detail.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description is sufficient for a simple read-only list operation, especially with detailed parameter schemas and strong annotations. It could be improved by noting usage distinctions from sibling tools, but it already covers the function, pagination, and return fields, making it complete for an agent.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 100% description coverage for all 5 parameters, each with clear descriptions. The tool description itself does not add any parameter semantics beyond what the schema already provides, so the baseline score of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states '查询配置历史版本列表' (query configuration history version list), identifying the verb (query) and resource (config history versions). It also specifies that it returns a paginated list with fields like id, opType, operator, and time, which distinguishes it from single-history retrieval tools.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies use for retrieving a list of historical versions but does not provide explicit when-to-use guidance or alternatives. It does not differentiate from sibling tools like get_config_history or get_config_previous, leaving the agent to infer the context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
查询命名空间下的配置列表。
对应 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 总数。
| Name | Required | Description | Default |
|---|---|---|---|
| search | No | 匹配模式：blur（默认）解释 dataId/group 中的通配符 '*' 做 LIKE 匹配；accurate 精确匹配。二者在不带通配符时行为一致（完整名命中、子串不命中） | blur |
| data_id | No | 按 dataId 过滤（可选）。search=blur 下需显式带通配符如 '*app*'，裸子串 'app' 不命中；完整 dataId 精确命中。 | |
| page_no | No | 分页页码，从 1 开始（默认 1） | |
| app_name | No | 按 appName 过滤（可选） | |
| page_size | No | 每页条数（默认 100） | |
| group_name | No | 按 group 过滤（可选，默认不过滤）；模糊匹配同 data_id，需显式带通配符 '*' | |
| config_tags | No | 按配置标签 config_tags 过滤（可选） | |
| namespace_id | No | 命名空间 ID；优先级：工具参数 > NACOS_NAMESPACE 环境变量 > 默认 public |
| Name | Required | Description |
|---|---|---|
| configs | No | |
| total_count | No | |
| namespace_id | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond the annotations (readOnlyHint, destructiveHint, idempotentHint), the description adds substantial behavioral context: search=blur does not auto-wildcard, substrings don't match unless wildcards are explicit, and the return includes a total count. It also discloses version-specific API endpoints. This goes well beyond minimal disclosure and enriches the agent's mental model.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured: a one-line purpose, a bulleted API mapping, a separate matching-semantics paragraph, and a clear return format statement. Every sentence serves a purpose, and the length is appropriate for the tool's complexity. No redundant content.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description fully covers the tool's purpose, filtering capabilities, matching behavior, return format, and version support. With an output schema present, it provides everything an agent needs to invoke the tool correctly and interpret results. No gaps detected.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema provides 100% coverage for all 8 parameters, including detailed descriptions of wildcard behavior for data_id and group_name. The description's matching semantics section essentially reiterates this schema information without adding new parameter-specific meaning. Thus the baseline of 3 applies, as the schema does the heavy lifting.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool queries the configuration list under a namespace, using the specific verb '查询' and resource '配置列表'. It differentiates from siblings like nacos_get_config by explicitly noting it returns metadata (data_id, group_name) and excludes config content, making the purpose unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear context for when to use the tool: it returns metadata only, not content, implying it is for listing rather than fetching full configs. It also explains matching semantics for fuzzy vs exact search. However, it does not explicitly name alternatives or state exclusions (e.g., 'use nacos_get_config for content'), so it misses the highest bar for explicit guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
查询命名空间列表。
对应 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，及每个命名空间的配额与使用量）。
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
| Name | Required | Description |
|---|---|---|
| namespaces | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnly, idempotent, and non-destructive behavior. The description adds value beyond annotations by specifying the exact API endpoints (v1/v2/v3) and clarifying the return content (includes public namespace, quota, and usage). This gives the agent a more concrete picture of what the tool does.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Description is compact and front-loaded with the core purpose, followed by structured endpoint references and a clear note on return content. No redundant sentences; each part adds context without bloat.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a zero-parameter list tool, the description is complete: it states what is listed, the namespace scope, and what information is returned. An output schema exists to define the exact return structure, so the description does not need to duplicate that. No gaps are apparent.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has zero parameters, so the input schema is empty. The description correctly avoids fabricating parameter explanations. Baseline 4 is appropriate because parameter semantics are trivially covered by the absence of parameters.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Description clearly states the action: '查询命名空间列表' (query namespace list) and specifies the resource. It distinguishes from sibling nacos_get_namespace by enumerating all namespaces including public, and mentions quota/usage. The verb and scope are specific and unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides clear context: use to retrieve all namespaces from the current Nacos instance, with added details about public namespace inclusion and quota/usage. It does not explicitly mention when not to use it or name alternatives, but the scope is sufficiently clear given the sibling context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
v0.7.0nacos_create_namespacenacos_delete_confignacos_delete_namespacenacos_get_namespace2 fields changedInput schema / properties / namespace_id / descriptionPrevious value: -"命名空间 ID。优先级：工具参数 > 环境变量 NACOS_NAMESPACE > 默认 public"New value: +"命名空间 ID。优先级：工具参数 > 环境变量 NACOS_NAMESPACE > 默认 public。查 public 传 'public' 或空串均可（工具会自动归一化：public 的真实 id 因版本而异，2.x 为空串，已统一处理）"Input schema / properties / namespace_id / minLengthRemoved value: -1nacos_list_configsnacos_publish_confignacos_update_namespacev0.4.0nacos_create_namespacenacos_delete_confignacos_delete_namespacenacos_get_confignacos_get_config_historynacos_get_config_previousnacos_get_namespacenacos_list_config_historynacos_list_namespacesnacos_publish_confignacos_update_namespaceScored 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.
Unclaimed servers have limited discoverability.
If you are the server author, to access and configure the admin panel.
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.
MCP server connecting AI agents to 100+ apps (Gmail, Slack, Notion, GitHub) via one-click OAuth.
Zero-setup MCP gateway securely connecting AI to your tools with authentication and workflows
