grpc-mcp

library2.0.1jsnpmunverified

grpc-mcp is a Node.js/TypeScript MCP server that enables gRPC unary requests and Protocol Buffer file information retrieval via natural language or MCP clients. Version 2.0.1 provides tools like loadProto, getMethodInformation, and sendRequest with support for SSL, timeout, and response time statistics. It uses @grpc/grpc-js for gRPC communication and fastmcp for the MCP framework. Key limitations: no streaming support, only unary RPCs. Alternative to direct gRPC clients for AI-assisted workflows.

ai-ml devops

npm install grpc-mcp

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · GRPC-MCP

grpc-mcp

ai-mljavascriptv2.0.1

harness data pending

Install & Compatibility

Where this runs

No compatibility data collected yet for this library.

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

loader

✓ import { loader } from 'grpc-mcp'

✗ import grpcMcp from 'grpc-mcp'

Named export for loading proto files. Do not use default import.

client

✓ import { client } from 'grpc-mcp'

✗ const { client } = require('grpc-mcp')

Named export for sending gRPC requests. CommonJS require is unsupported; package is ESM-only.

GrpcMcpServer

✓ import { GrpcMcpServer } from 'grpc-mcp'

✗ import { GrpcMcpServer } from 'grpc-mcp/dist/index.js'

Class for creating a custom MCP server. Do not use internal dist path; it may break between versions.

Shows how to import loader and client, load a proto file, get method info, and send a unary gRPC request.

import { loader, client } from 'grpc-mcp'; async function main() { // Load proto files from directory const protoList = await loader.loadAsync('./protos'); const myProto = protoList[0]; // Get method information const methodInfo = await myProto.getMethodInformation('MyService', 'MyMethod'); console.log('Method info:', methodInfo); // Send a gRPC request const result = await client.sendRequest({ path: './protos/my.proto', address: 'localhost:50051', service: 'MyService', method: 'MyMethod', body: JSON.stringify({ id: 1 }), config: { SSL: false, deadline: 5000 } }); console.log('Response:', result.response.body); } main().catch(console.error);

Debug

Known issues

breakinggRPC streaming (server, client, bidirectional) is NOT supported. Only unary RPCs work.

fix

Use a different gRPC client like @grpc/grpc-js directly for streaming.

affects: >=2.0.0

deprecatedThe method 'loadProto' (tool) may be deprecated in favor of 'loadAsync' API.

fix

Use loader.loadAsync() instead of loadProto tool for programmatic usage.

affects: >=2.0.0

gotchaBody parameter for sendRequest must be a JSON string, not a JavaScript object.

fix

Wrap the object with JSON.stringify() before passing as body.

affects: >=1.0.0

gotchaThe package is ESM-only; require() will fail with ERR_REQUIRE_ESM.

fix

Use import syntax or use dynamic import() for CommonJS projects.

affects: >=2.0.0

gotchaPaths to .proto files must be absolute on Windows; relative paths may be relative to CWD.

fix

Use path.resolve() to create absolute paths from user input.

affects: >=1.0.0

Errors

Common errors & fixes

Error: Cannot find module 'grpc-mcp'

Package not installed or import path incorrect in CommonJS.

fix

Install with npm install grpc-mcp. For CommonJS, use import() or switch to ESM.

TypeError: loader.loadAsync is not a function

Incorrect import – possibly using default import instead of named export.

fix

Use import { loader } from 'grpc-mcp' instead of import loader from 'grpc-mcp'.

Error: 2 UNKNOWN: Unimplemented method

The gRPC server does not expose the requested method or service name is misspelled.

fix

Verify the service and method names using getMethodInformation tool.

Upgrade

Version history

2.0.1latest on npm

Audit

Dependencies

@grpc/grpc-jsrequiredCore gRPC client library for making requests

@grpc/proto-loaderrequiredLoads .proto files to define gRPC services

fastmcprequiredMCP server framework for tool definitions and transport

zodrequiredSchema validation for tool parameters

Agent activity

22 hits · last 30 days

node

OpenAI (training)

Resources

githubhttps://github.com/Yuki4-dev/grpc-mcp ↗

packagegrpc-mcp ↗

homepagehttps://github.com/Yuki4-dev/grpc-mcp#readme ↗