Dubbo-MCP

One question → service discovery → method schema → real RPC → answer. The 15-second GIF plays and loops directly on this page—no click needed. Real test-environment MCP calls; rendered replay, not Codex CLI footage. Source & recording guide

Dubbo-MCP is a Model Context Protocol (MCP) server that connects AI coding assistants (Cursor, Claude Code, Claude Desktop, Codex CLI, Windsurf, etc.) directly to Apache Dubbo microservices.

During daily troubleshooting, interface debugging, and unit testing, it allows AI coding agents to discover registered service definitions, inspect complex DTO parameter structures, and execute real-time RPC calls via native Generic Invocation — with no need to write manual test cases and zero requirement to import API dependency JARs into local projects.

💡 What It Feels Like (Cursor / Claude Desktop)

Instead of manually logging into Dubbo Admin web consoles, flipping through Swagger docs, or writing throwaway test scripts, simply converse with your AI assistant:

The following interaction uses fictional interface names and sample data.

Developer: "Query the warehouse service in the test environment and fetch stock details for warehouse ID 2001."

AI Agent (via Dubbo-MCP):

1. 🔍 dubbo_list_services(keyword="Warehouse")
   ↳ Discovers target service: com.example.warehouse.api.WarehouseServiceRpc:1.0.0

2. 📋 dubbo_get_service_detail(interfaceName="...")
   ↳ Introspects signature: queryStock(com.example.warehouse.dto.WarehouseQueryDTO)

3. ⚡ dubbo_invoke(interfaceName="...", method="queryStock", args=[{"warehouseId": 2001}])
   ↳ Native Dubbo generic invocation executed in 14 ms

Real-time response returned to chat:

{
  "code": 200,
  "data": {
    "warehouseId": 2001,
    "warehouseName": "East China Regional Distribution Center #1",
    "availableStock": 1420,
    "lockedStock": 35,
    "status": "OPERATIONAL"
  }
}

Related MCP server: Open Enterprise AI MCP Server

🚀 Quick Start

1. One-Line Script Installation

macOS / Linux:

curl -fsSL https://raw.githubusercontent.com/b1n9bna/dubbo-mcp/main/install.sh | sh

Windows (PowerShell):

irm https://raw.githubusercontent.com/b1n9bna/dubbo-mcp/main/install.ps1 | iex

The script downloads the standalone executable to ~/.dubbo-mcp/dubbo-mcp.jar and creates a global command dubbo-mcp.

(Or compile locally from source: mvn clean package -DskipTests)

2. Auto-Wire AI Coding Agents

After installation, run the following command to automatically detect and configure installed AI agents (Codex, Cursor, Claude Desktop):

dubbo-mcp install

⚙️ Configuration

Configuration file location: ~/.dubbo-mcp/config.properties

# Default active environment (test / uat / prod)
active.env=test

# ==============================================================================
# 1. Dev / Test Environment (Direct ZooKeeper connection, Generic Invocation)
# ==============================================================================
env.test.type=zookeeper
env.test.registry=zookeeper://127.0.0.1:2181
env.test.timeout=5000
env.test.readonly=false

# ==============================================================================
# 2. Staging / UAT Environment
# ==============================================================================
env.uat.type=zookeeper
env.uat.registry=zookeeper://10.20.1.15:2181
env.uat.timeout=5000
env.uat.readonly=true

# ==============================================================================
# 3. Production Environment (Proxy via Dubbo Admin HTTP API)
# ==============================================================================
env.prod.type=dubbo-admin
env.prod.admin_url=https://dubbo.yourcompany.com
env.prod.readonly=true
env.prod.data_masking=true

# Read-only method regex guard: when readonly=true, only matching methods are permitted
security.readonly.regex=^(get|query|find|select|list|count|check|is|search|fetch|read).*$

# Custom dubbo-admin context path (optional, e.g. /dubbo-admin)
# env.prod.admin_api_prefix=/dubbo-admin

🔐 Production Authentication (dubbo-admin)

Enterprise Dubbo Admin consoles are typically secured behind corporate Single Sign-On (SSO / OAuth). When configured with env.prod.type=dubbo-admin, save credentials once via terminal upon first run or after session expiry:

Browser login: With Chrome or Edge installed, run:

dubbo-mcp login --browser

The command checks saved credentials first. If login is needed, it opens a dedicated browser window; complete your normal login and credentials are automatically verified and saved. The dedicated profile is separate from your everyday browser. Use --browser=edge to select Edge, or --env=NAME for another configured Admin environment.

The existing clipboard workflow remains available:

1. Copy Session in Browser: Log into your company's Dubbo Admin console, press F12 to open Developer Tools Console, and run:

   copy(JSON.stringify({
     cookie: document.cookie,
     authorization: localStorage.getItem('token') || localStorage.getItem('Admin-Token')
   }))

2. Save Credentials in Terminal: Run the following in your terminal (macOS --clipboard reads directly from the system clipboard to prevent terminal line buffer truncation):

   dubbo-mcp login --clipboard

Validated credentials are saved securely in ~/.dubbo-mcp/session-prod.json (permissions 0600). Running MCP instances automatically hot-reload renewed credentials on the next request without restarting your AI assistant.

🔌 Manual Agent Configuration

If you do not use dubbo-mcp install for automated setup, you can manually configure your tools:

Codex

Add to ~/.codex/config.toml:

[mcp_servers.dubbo]
command = "dubbo-mcp"
args = []

Cursor

Add to .cursor/mcp.json:

{
  "mcpServers": {
    "dubbo": {
      "command": "dubbo-mcp",
      "args": []
    }
  }
}

Claude Code / ZCode

Add via Git repository:

/plugin marketplace add https://github.com/b1n9bna/dubbo-mcp.git

Or configure as a stdio command dubbo-mcp.

💬 Usage Examples

Once configured, interact with your microservices using plain natural language in your AI chat:

Scenario 1: Troubleshooting Production Issues

Prompt: "Query order 2026103001 in production and analyze why it hasn't shipped yet."
AI Workflow:

1. Calls dubbo_invoke (env="prod", interfaceName="com.corp.OrderQueryService", method="getOrderDetail");

2. Dubbo-MCP proxies the call via Dubbo Admin and automatically masks sensitive fields (phone numbers, national IDs);

3. AI analyzes the returned JSON: "The order status is PAID, but the logistics tracking number is null. The order is currently held in STOCKING status."

Scenario 2: Service & Interface Discovery

Prompt: "What Dubbo services related to 'user' are available in the test environment? List their methods and parameter structures."
AI Workflow:

1. Calls dubbo_list_services(keyword="user") to retrieve matching interfaces;

2. Calls dubbo_get_service_detail to inspect method signatures and DTO properties;

3. Summarizes available methods for subsequent invocations.

Scenario 3: Switching Environments Dynamically

Prompt: "Switch the active environment to UAT."
AI Workflow: Calls dubbo_switch_env(env="uat"). Subsequent requests seamlessly route to the UAT cluster.

🛠️ MCP Tools Reference

🛡️ Enterprise Production Reliability

To safeguard production invocation and LLM stability:

1. Dual-Track Service Search: User queries like "oms" match services by both interface package names and provider application names (e.g. com.example.trade.OrderRpcService (app: oms-provider)).

2. Precision Loss Prevention & Type Coercion: 64-bit Snowflake IDs and order numbers passed as strings (e.g. "202610080001") are safely coerced into Long, BigDecimal, or DTO maps without JavaScript 53-bit floating-point truncation. Conversions to int/long reject fractional, non-finite, and out-of-range values before invocation.

3. Implicit Arguments (RpcContext Attachments): Forward multi-tenant IDs, trace IDs, and routing tags via request attachments or environment properties (env.<env>.attachment.<key>).

4. Context Explosion Protection & JSONPath: Responses larger than 24KB of UTF-8 bytes are structured-truncated into valid JSON envelopes with extraction hints, and jsonPath (e.g. $.data.items[0]) allows targeted extraction. JSONPath syntax is validated before RPC execution. mcp.max_response_bytes sets the byte cap; limits too small to fit the minimal truncation envelope are rejected before invocation.

5. Provider Signature Self-Healing: When metadata reports are absent, provider reflection errors (Available methods: [...]) are transformed into actionable parameter type advice for zero-touch LLM self-healing.

6. Read-Only Method Regex Guard: In environments with readonly=true, mutating operations (update*, delete*, save*) are blocked immediately. Boolean settings accept only true or false; invalid values stop the call.

7. Sensitive Data Masking: Automatic masking for Chinese mobile numbers (138****5678) and National IDs (110101********2345), including tool error messages when data_masking=true.

🏗️ Architecture & How It Works

 ┌────────────────────────────────────────────────────────┐
 │   AI Coding Agents (Cursor / Claude Code / Codex CLI)   │
 └───────────────────────────┬────────────────────────────┘
                             │
                STDIO Transport (JSON-RPC 2.0)
                             │
 ┌───────────────────────────▼────────────────────────────┐
 │  1. Transport Layer: StdioJsonRpcServer (Pure Java 8)  │
 │     - Redirects logs to stderr; stdout pure JSON-RPC   │
 ├────────────────────────────────────────────────────────┤
 │  2. Security Guard & Two-Stage Scheduler Layer         │
 │     - On-demand: Discover -> Inspect Metadata -> Call  │
 │     - Production Protection: Read-Only Regex + Masking │
 ├────────────────────────────────────────────────────────┤
 │  3. Dual-Engine Driver Core                            │
 │     - Dev/Test: Direct ZooKeeper, native Generic RPC   │
 │     - Production: Proxy via Dubbo Admin HTTP Gateway   │
 └───────────────────────────┬────────────────────────────┘
              ┌──────────────┴──────────────┐
              ▼                             ▼
     [Dev/Test: ZooKeeper]       [Production: HTTP Relay]
      Dubbo Provider Nodes        Corporate Dubbo Admin

📊 Performance & Token Benchmark

Empirical Result: In a real service troubleshooting session, Dubbo-MCP's structured RPC invocation saves ~98.6% context tokens and responds 30× faster compared to browser-based automation agents, completely avoiding webpage DOM noise and cascading screenshot history overhead.

1. LLM Context Overhead Comparison (Single Troubleshooting Session)

• Tokenization Benchmark: Measured with OpenAI cl100k_base BPE tokenizer, based on an actual production order troubleshooting workflow;

• Dubbo-MCP: tools/list schema (397 tokens) + single tool call request (51 tokens) + actual RPC response (90 tokens) + AI summary (34 tokens) = 572 tokens;

• Vision Browser Agent: Anthropic official vision formula (1280×800 screenshot ≈ 1,365 tokens/image). Navigating Dubbo Admin (search -> click -> fill inputs -> submit -> view popup) required 6 screenshot rounds, calculated with compounding conversational history ($O(N^2)$);

• DOM Browser Agent: Dubbo Admin (Vue + Element UI) rendered accessibility DOM tree (~2,500 tokens/step), across 5 state-machine iterations with compounding history.

2. Local Process Resource Footprint

❓ FAQ

Dubbo-MCP relies on native Dubbo Generic Invocation (GenericService):

• Schema Introspection: Calling dubbo_get_service_detail inspects the ZooKeeper metadata report to determine DTO properties (e.g. current, size, calculationDateList);

• Automatic Type Matching: The AI agent passes standard JSON maps in args. The underlying driver matches target DTO definitions and handles serialization automatically.

• The driver automatically queries registered provider URLs. If an interface has only a single version and group, it is selected automatically;

• When multiple versions or groups exist, explicitly provide version or group parameters in dubbo_invoke for targeted routing.

If your corporate SSO session expires, requests return HTTP 401/403. Simply log into Dubbo Admin again in your browser, copy the credentials via Console, and re-run dubbo-mcp login --clipboard. The active MCP process hot-reloads the new credentials on the next invocation without needing a restart.

Running dubbo-mcp install automatically configures ~/.cursor/mcp.json. In Cursor chat, type natural language prompts such as:

• "Inspect the parameter structure of com.example.trade.OrderRpcService in production"

• "Invoke UserServiceRpc.getUserById in the test environment with userId=10001"

Cursor automatically executes dubbo_get_service_detail to retrieve signatures and calls dubbo_invoke to return real-time JSON results without leaving your editor.

• 98.6% Token Savings: Real-world inspections require only 572 tokens vs 33,000 ~ 40,000 tokens for browser agents;

• Sub-Second Latency: Direct RPC responses avoid webpage rendering, DOM parsing, simulated typing, and screenshot latencies (which take 30~60s);

• Deterministic & Safe: Completely immune to frontend UI redesigns or popup misclicks, with strict read-only regex guards and automated sensitive data masking.

• Dubbo Admin Mode (type=dubbo-admin): Fully supported out of the box. Dubbo Admin aggregates service registries at the server layer, natively supporting Nacos, ZooKeeper, Consul, and Apollo. If your infrastructure uses Nacos + Dubbo Admin, dubbo-mcp connects seamlessly without additional settings.

• Direct Mode (type=zookeeper): ZooKeeper is natively supported for direct cluster calls without Dubbo Admin. Direct standalone driver support for Nacos is on the active roadmap.

💻 Local Build & Test

# Run unit test suite
LANG=en_US.UTF-8 LC_ALL=en_US.UTF-8 mvn test

# Build shaded Fat-JAR
LANG=en_US.UTF-8 LC_ALL=en_US.UTF-8 mvn package -DskipTests

Discovery and installation failures

Admin discovery follows recognized pagination cursors (Spring page, MyBatis current, PageHelper pageNum, and currPage). An incomplete, repeated, or unverifiable page causes an error instead of selecting from partial results; discovery is bounded to 100 pages. Authentication, network, and server failures are preserved. Endpoint fallback is restricted to HTTP 404/405/501 and is shared by login verification and service discovery. Complete explicit paramTypes avoid metadata requests during invocation.

dubbo-mcp install distinguishes configured, skipped, and failed clients. An absent optional client can be skipped; any configuration write failure produces a nonzero exit status, including partial failures.

Runtime responsiveness and startup errors

Existing user configuration that cannot be read or parsed stops startup; it never silently changes the target environment to the bundled default. Missing user configuration still uses the bundled defaults.

Tools execute serially through a queue with 16 waiting slots, preserving environment-switch ordering. Protocol control messages such as ping remain responsive during tool calls. mcp.request_timeout_ms bounds each accepted tool request, including queue time (default 60000 ms). A full queue returns an explicit error without executing the rejected request. MCP cancellation notifications cancel queued work and interrupt running work without returning the cancelled response. Cancellation and timeout cannot guarantee rollback of a remote write; do not automatically retry writes. On stdin EOF, the server allows mcp.shutdown_timeout_ms (default 5000 ms) for accepted work to finish, then cancels remaining work.

The POSIX installer creates the shell startup file if absent and adds its PATH entry idempotently. Run python3 scripts/smoke_install.py for the offline first-install regression.

STDIO frames are limited to mcp.max_request_bytes (default 1 MiB, configurable from 1 byte to 8 MiB). Oversized frames are discarded through the next line delimiter and receive an error with a null ID; subsequent messages remain usable. python3 scripts/smoke_limits.py target/dubbo-mcp.jar verifies recovery in a disposable 24 MiB JVM.

Configuration files use strict UTF-8 (optional BOM); Java \uXXXX escapes remain supported. Invalid encoding aborts startup. Failed Admin context detection is not cached, allowing the next request to recover after a transient outage; admin_api_prefix can explicitly select a root or custom deployment.

Admin HTTP bodies are bounded before decoding/parsing by env.<env>.admin_max_response_bytes (default 1 MiB, configurable up to 16 MiB). The bound applies to decompressed gzip data as well as known-length and chunked responses, including login and context discovery. Oversized responses return an error; reduce the remote page size or adjust this bound.

ZooKeeper service discovery respects the registry URL's group namespace, for example zookeeper://127.0.0.1:2181?group=team-a. This is separate from env.<env>.group, which selects a Dubbo service group such as blue.

Windows installation prioritizes target/dubbo-mcp.jar, with the legacy 1.0.0-SNAPSHOT fat JAR as a fallback. Versioned thin Maven JARs are not installed. scripts/smoke_install.ps1 tests selection, offline download fallback and preservation of the installed JAR after validation failure in Windows CI.

The runtime no longer ships Jackson. OkHttp is pinned to 4.12.1, ZooKeeper to 3.8.7, and all Netty modules to 4.1.137.Final. Curator stays on 4.2.0 for Dubbo 2.7 compatibility; SLF4J Simple is the only logging provider. Local integration tests cover ZooKeeper registration, discovery, generic invocation, and TLS trust/hostname rejection. python3 scripts/check_runtime_dependencies.py target/dubbo-mcp.jar checks the packaged dependency boundaries.

For native ZooKeeper/Dubbo mode on Java 17/21, Dubbo 2.7 requires reflection access. Add --add-opens=java.base/java.lang=ALL-UNNAMED and --add-opens=java.base/java.math=ALL-UNNAMED before -jar in the Java command or your MCP server's args. These flags are unnecessary on Java 8/11 and for HTTP Admin mode. Maven enables them for integration tests on JDK 16+. Client library upgrades do not upgrade remote ZooKeeper servers.