gRPC Invoke MCP

gRPC Invoke MCP

grpc-invoke-mcp é um servidor MCP para chamar métodos gRPC a partir de agentes de IA como Claude Code, Codex, Cursor e outras ferramentas compatíveis com MCP.

Ele oferece aos agentes uma maneira simples de inspecionar APIs gRPC e invocar RPCs unários usando reflection do servidor ou arquivos .proto locais. Isso é útil quando você quer que um agente explore serviços, entenda esquemas de requisição e resposta, faça chamadas gRPC reais e teste integrações gRPC durante o desenvolvimento orientado por agentes, sem precisar escrever scripts avulsos.

Recursos

• Chame métodos gRPC a partir de agentes compatíveis com MCP
• Descreva serviços, métodos e tipos de mensagem gRPC
• Use reflection do servidor ou arquivos .proto locais
• Conecte-se via TLS ou HTTP/2 em texto puro
• Envie cabeçalhos de metadados personalizados
• Passe corpos de requisição JSON para RPCs unários
• Funciona com Claude Code, Codex, Cursor e outros clientes MCP

Instalação

Execute o servidor com npx:

npx -y @grulex/grpc-invoke-mcp@latest

O pacote baixa um binário grpc-invoke-mcp específico da plataforma durante a instalação.

Configuração do Agente

Claude Code

Arquivo de configuração do projeto: .mcp.json

{
  "mcpServers": {
    "grpc-invoke": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@grulex/grpc-invoke-mcp@latest"]
    }
  }
}

Configuração opcional via CLI:

claude mcp add --transport stdio grpc-invoke -- npx -y @grulex/grpc-invoke-mcp@latest

Codex

Arquivo de configuração do usuário: ~/.codex/config.toml

[mcp_servers.grpc-invoke]
command = "npx"
args = ["-y", "@grulex/grpc-invoke-mcp@latest"]

Configuração opcional via CLI:

codex mcp add grpc-invoke -- npx -y @grulex/grpc-invoke-mcp@latest

Cursor

Arquivo de configuração do projeto: .cursor/mcp.json

{
  "mcpServers": {
    "grpc-invoke": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@grulex/grpc-invoke-mcp@latest"]
    }
  }
}

Você também pode instalá-lo globalmente em ~/.cursor/mcp.json.

Ferramentas Disponíveis

grpc_describe

Use esta ferramenta para inspecionar serviços, métodos e tipos de mensagem.

Casos de uso comuns:

• listar serviços expostos por um servidor gRPC
• inspecionar a assinatura de um método antes de chamá-lo
• explorar esquemas de mensagem por meio de reflection
• descrever APIs a partir de arquivos .proto locais

grpc_call

Use esta ferramenta para invocar métodos gRPC unários com um corpo de requisição JSON.

Casos de uso comuns:

• chamar microsserviços internos a partir do seu agente
• testar cargas úteis de requisição e resposta
• enviar cabeçalhos de autenticação ou outros metadados gRPC
• conectar-se a endpoints locais, de staging ou seguros para produção

Exemplos de Prompts

• "Descreva os serviços expostos por localhost:50051 usando reflection."
• "Mostre o esquema de requisição para helloworld.Greeter/SayHello."
• "Chame helloworld.Greeter/SayHello em localhost:50051 com { \"name\": \"World\" }."
• "Invoque package.Service/Method usando proto_files e import_paths em vez de reflection."

Como Funciona

Este pacote expõe um servidor MCP via stdio. Seu agente o inicia localmente e descobre ferramentas como:

• grpc_describe para inspeção de esquemas
• grpc_call para invocação de RPC unário

Internamente, o pacote npm inicia um binário nativo grpc-invoke-mcp incluído no momento da instalação. O binário suporta:

• reflection de servidor gRPC
• definições locais de .proto
• conexões em texto puro ou TLS
• cabeçalhos de metadados de requisição

Plataformas Suportadas

O instalador atualmente tem como alvo:

• macOS Apple Silicon
• macOS Intel
• Linux x64
• Linux ARM64
• Windows x64
• Windows ARM64

Solução de Problemas

npx não consegue iniciar o servidor

Certifique-se de que Node.js e npx estejam instalados e disponíveis no seu PATH.

O download do binário falha

O pacote npm baixa um artefato de release durante a instalação, então sua máquina precisa de acesso à rede para GitHub Releases.

Reflection não funciona

Se o servidor de destino não expõe reflection gRPC, use arquivos .proto locais e import_paths como alternativa.

Erros de TLS ou conexão

Verifique o host de destino, a porta, as configurações de TLS e se o servidor espera texto puro ou TLS.

O agente não usa o servidor MCP

Confirme se o arquivo de configuração está no local correto para o seu cliente, reinicie o cliente se necessário e verifique se o servidor aparece na lista MCP ou no painel de ferramentas.

Por que Usar grpc-invoke-mcp

Se você trabalha com serviços gRPC, este servidor MCP permite que agentes de IA inspecionem e chamem esses serviços diretamente. Em vez de traduzir detalhes da API manualmente, você pode deixar Claude Code, Codex, Cursor ou outros agentes compatíveis com MCP explorarem o contrato e executarem requisições seguras e direcionadas para depuração, trabalho de integração, descoberta de API e testes gRPC em fluxos de trabalho de desenvolvimento orientados por agentes.

Licença

MIT