Just A Nacos

Read your Nacos 3.0.x configuration directly from your AI agent.

No official Nacos MCP exists for v3 — this fills that gap.

Read-only by design. All tools are read operations only. Write operations will never be added — an agent writing config with a wrong namespace or at the wrong moment can cause production-level incidents. Just because we can doesn't mean we should.

What it does

Once connected, your AI agent (Kiro, Claude Desktop, Cursor, etc.) can:

• List namespaces — see all environments in your Nacos server
• List configs — browse configs in any namespace, with fuzzy filtering by dataId or group
• Get a config — fetch content and full metadata (md5, type, created by, timestamps)
• Search by content — find all configs containing a specific keyword

Requirements

• uv — brew install uv
• Nacos 3.0.x server (tested on 3.0.3)

Setup

1. Clone and install

git clone https://github.com/xingyuli/just-a-nacos-mcp
cd just-a-nacos-mcp
uv sync

2. Add to your AI agent

Add this to your MCP config file (.kiro/settings/mcp.json for Kiro, or ~/Library/Application Support/Claude/claude_desktop_config.json for Claude Desktop):

{
  "mcpServers": {
    "nacos": {
      "command": "uv",
      "args": [
        "--directory", "/path/to/just-a-nacos-mcp",
        "run", "nacos_mcp_server.py"
      ],
      "env": {
        "NACOS_URL": "http://your-nacos-host:8848",
        "NACOS_AUTH": "true",
        "NACOS_USERNAME": "your-username",
        "NACOS_PASSWORD": "your-password"
      }
    }
  }
}

If your credentials are already exported in ~/.zprofile or ~/.zshrc, you can reference them directly:

"NACOS_URL": "${NACOS_URL}",
"NACOS_USERNAME": "${NACOS_USERNAME}",
"NACOS_PASSWORD": "${NACOS_PASSWORD}"

3. Restart your agent and start asking questions like:

• "List all namespaces on Nacos"
• "Show me all configs in the dev namespace"
• "Get the content of datasource.yaml in group DEFAULT_GROUP"
• "Which configs contain the word 'redis'?"

Configuration

Console port vs gRPC port: Every Nacos server (standalone or cluster) exposes two ports. Port 8848 (HTTP) serves the web console, REST API, and this MCP server. Port 9848 (gRPC, offset +1000) is used exclusively by Spring Cloud / SDK clients. NACOS_URL must point to the HTTP port.

Token refresh

Authentication tokens are cached and refreshed automatically before they expire. No manual intervention needed.

For implementation details, endpoint reference, and contributing guide, see DEVELOPMENT.md.