@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

• Connect to a gRPC server:

  connect_endpoint(endpoint="localhost:50051")
  

• Discover available services:

  list_services()
  

• Inspect a service's methods:

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

• 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

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

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

License

MIT