spring-nacos-mcp

中文文档

A project-aware, read-only Nacos MCP server for Spring Cloud repositories.

Point it at your Spring Cloud repo. It reads your own application-* / bootstrap-* files, discovers every environment (dev / test / pre / prod / ...), and gives your AI assistant read-only Nacos tools across all of them — no host, port, namespace or token to configure.

You:    "Is sso.server.productCode consistent between dev and test?"

Claude: → nacos_search_config(env=dev, keyword=sso.server.productCode)
        → nacos_diff_config(env_a=dev, env_b=test, data_id=sso.properties)

        "Yes — the value is identical in both environments (`PC-1001`).
         One related key differs though: sso.server.url points to
         dev-sso.corp.com in dev and test-sso.corp.com in test."

Why not the official nacos-mcp-server?

The official nacos-group/nacos-mcp-server connects to one cluster that you configure by hand (--host, --port, --access_token). That's the right tool for operating a Nacos cluster.

This project answers a different question: "what does my project's config look like across environments?"

	official nacos-mcp-server	spring-nacos-mcp
Setup	manual host/port/token per cluster	zero-config: parsed from your repo
Environments	one per server instance	all profiles, env param on every tool
Cross-env diff	not possible (single cluster)	built-in nacos_diff_config
Spring awareness	none	shared-configs, file-extension, app config
Write operations	planned	never (read-only by design)

Quickstart

The easy way: let your AI agent install it

Paste this into Cursor / Claude Code / Codex / Trae:

Install the MCP server from https://github.com/kestiny18/spring-nacos-mcp into this project and verify it works.

The repo ships an llms-install.md with exact steps per client, so the agent can do the whole thing — download, config, verification — by itself.

Manual, option A: copy one file (no PyPI, no dependencies)

The whole server is a single, zero-dependency, standard-library-only Python file. Drop it into your repo:

curl -sfL -o tools/nacos_mcp.py https://raw.githubusercontent.com/kestiny18/spring-nacos-mcp/main/src/spring_nacos_mcp/server.py

// .cursor/mcp.json or .mcp.json (Claude Code), at the repo root
{
  "mcpServers": {
    "spring-nacos-mcp": { "command": "python", "args": ["tools/nacos_mcp.py"] }
  }
}

Works on intranet machines too — copy the file over however you like.

Manual, option B: uv / pip straight from git

{
  "mcpServers": {
    "spring-nacos-mcp": {
      "command": "uvx",
      "args": ["--from", "git+https://github.com/kestiny18/spring-nacos-mcp", "spring-nacos-mcp"]
    }
  }
}

Or pip install git+https://github.com/kestiny18/spring-nacos-mcp and use the spring-nacos-mcp command.

The server auto-detects the repo root from its working directory (your editor's workspace). For clients that don't launch servers in the workspace (e.g. Claude Desktop), pin it: "args": [..., "--repo", "/path/to/repo"].

Verify your setup

python tools/nacos_mcp.py --check       # or: spring-nacos-mcp --check

Prints every discovered environment, where it came from, and whether the Nacos server is reachable. Exit codes: 0 all reachable · 1 nothing discovered · 2 discovered but some unreachable (usually VPN/network, not setup).

Tools

Tool	What it does
nacos_list_envs	List discovered environments with address/namespace/groups
nacos_get_config	Read one config's raw content by dataId
nacos_get_app_config	App config + the shared/extension configs your project declares
nacos_list_configs	List dataIds in a namespace (optional fuzzy filter)
nacos_search_config	Full-text search across all config contents
nacos_diff_config	Key-level diff of one config between two environments
nacos_list_services	List services in the discovery registry
nacos_list_instances	List online instances (IP/port/health) of a service

How discovery works

1. Find the repo root (.git, pom.xml, build.gradle, mvnw, gradlew, ...).
2. Scan every */src/main/resources/ for application[-<profile>].{yml,yaml,properties} and bootstrap[-<profile>].{yml,yaml,properties}. Multi-document YAML with spring.config.activate.on-profile (or legacy spring.profiles) is supported.
3. For each profile, merge sources in priority order: bootstrap-<profile> → application-<profile> → base bootstrap → base application.
4. Extract spring.cloud.nacos.*: server-addr, namespace, username/password, config group (also from spring.config.import: nacos:...?group=X), discovery group, file-extension, shared-configs / extension-configs / legacy shared-dataids. Relaxed binding (server-addr / serverAddr / server_addr) is handled.
5. ${...} placeholders are resolved from environment variables (${nacos.addr} also tries NACOS_ADDR); ${name:default} uses the default. Environments with unresolved placeholders are skipped with a clear log line.

Overrides

Environment variables (highest precedence), <ENV> is the upper-cased profile name:

NACOS_DEV_SERVER_ADDR / NACOS_DEV_NAMESPACE / NACOS_DEV_USERNAME /
NACOS_DEV_PASSWORD / NACOS_DEV_GROUP / NACOS_DEV_CONTEXT_PATH
NACOS_USERNAME / NACOS_PASSWORD          # global fallback credentials

Or a .spring-nacos-mcp.yml at the repo root — patch discovered environments or define ones that aren't in the repo at all:

envs:
  staging:
    server-addr: nacos-staging.corp.com:8848
    namespace: ns-staging
    username: readonly
    password: ${STAGING_NACOS_PASSWORD}   # resolved from env var

Security notes

• Read-only by construction: the only endpoints ever called are config/service GET queries and the login endpoint. There is no code path that writes to Nacos.
• Config content reaches the LLM. If your configs contain secrets, enable masking: SPRING_NACOS_MCP_MASK=1 masks values whose keys contain password/secret/token/credential/..., or provide your own list: SPRING_NACOS_MCP_MASK=password,apikey. Masking is off by default.
• Prefer a read-only Nacos account (via NACOS_USERNAME / NACOS_PASSWORD) over credentials committed in config files.

Compatibility

• Python ≥ 3.9, zero runtime dependencies.
• Nacos 1.x / 2.x via the v1 OpenAPI; auth via /v1/auth/login with automatic fallback to /v3/auth/user/login (Nacos 3.x). https:// server addresses and comma-separated cluster address lists are supported.
• Nacos 3.x keeps v1 OpenAPI compatibility in current releases; if your deployment disables it, please open an issue — a v3 API backend is on the roadmap.

Limitations

• The built-in YAML parser covers the subset used by Spring config files (nested maps, lists, multi-document). Anchors and flow collections are ignored.
• Placeholders that come from Maven profile filtering (@...@) are not resolved; use the override file for those repos.

License

Apache-2.0