@supernova123/grpc-mcp-server

@supernova123/grpc-mcp-server

Connect AI agents to any gRPC service — no proto files needed.

Most gRPC services are invisible to AI tools. This MCP server uses gRPC Server Reflection to auto-discover services, methods, and types at runtime, then exposes them as callable tools for Claude, Cursor, and any MCP-compatible agent.

Why This Matters

gRPC powers Kubernetes, Istio, Envoy, and thousands of microservices — but AI agents can't talk to any of them. Until now, you'd need to manually define proto schemas, generate clients, and wire everything together. This server does it automatically: point it at any gRPC endpoint with reflection enabled, and it discovers everything.

Use cases:

• Debug microservices by invoking RPCs directly from Claude
• Inspect live service meshes (Istio, Envoy) without kubectl
• Build AI-powered ops tools that query gRPC health endpoints
• Prototype API integrations without writing client code
• Test gRPC services during development with natural language

Tools

| Tool | Description | |------|-------------| | connect_endpoint | Connect to a gRPC server and auto-discover all services via reflection | | list_services | List every gRPC service on the connected endpoint | | list_methods | List all RPC methods for a service (unary, server-stream, client-stream, bidi) | | get_service_descriptor | Get full service schema: methods, request/response types, streaming modes | | invoke_rpc | Call any RPC method with a JSON-serialized request body | | health_check | Standard gRPC Health Checking Protocol (v1) | | disconnect | Clear cached service data and disconnect |

Quick Start

Claude Desktop

Add to your claude_desktop_config.json:

{
  "mcpServers": {
    "grpc": {
      "command": "npx",
      "args": ["-y", "@supernova123/grpc-mcp-server"],
      "env": {
        "GRPC_ENDPOINT": "localhost:50051"
      }
    }
  }
}

Cursor / VS Code

{
  "mcp": {
    "servers": {
      "grpc": {
        "command": "npx",
        "args": ["-y", "@supernova123/grpc-mcp-server"],
        "env": {
          "GRPC_ENDPOINT": "localhost:50051"
        }
      }
    }
  }
}

Direct

npx @supernova123/grpc-mcp-server

Example Usage

1. Connect to a gRPC server:

   connect_endpoint(endpoint="localhost:50051")

1. Discover available services:

   list_services()

1. Inspect a service's methods:

   list_methods(service_name="grpc.health.v1.Health")

1. Invoke an RPC:

   invoke_rpc(
     service_name="grpc.health.v1.Health",
     method_name="Check",
     request={"service": ""}
   )

Environment Variables

| Variable | Description | Default | |----------|-------------|---------| | GRPC_ENDPOINT | Target gRPC endpoint (host:port) | (none — use connect_endpoint) | | GRPC_TIMEOUT_MS | Request timeout in milliseconds | 10000 | | GRPC_USE_TLS | Enable TLS connections | false |

Requirements

• Node.js 18+
• Target gRPC server must support gRPC Server Reflection (v1)

Most gRPC servers have reflection enabled in development. For production servers, ensure grpc.reflection.V1Reflection is registered.

How It Works

1. Connects to your gRPC endpoint via the reflection API
2. Fetches the full service descriptor (services → methods → types)
3. Dynamically generates MCP tool definitions from the schema
4. Invokes RPCs by serializing JSON requests to protobuf and back

No proto files. No code generation. No compile step.

License

MIT