Metadata-Version: 2.4
Name: grpcurl-mcp
Version: 0.1.1
Summary: MCP server that wraps grpcurl
Requires-Python: >=3.11
Description-Content-Type: text/markdown
Requires-Dist: mcp>=1.27.1

# grpcurl MCP Server

MCP server that wraps [`grpcurl`](https://github.com/fullstorydev/grpcurl) for calling gRPC APIs.

## Tools

- **`grpc_invoke`** — Execute a gRPC method. Parameters: `url` (required, e.g. `host:443`), `endpoint` (required, e.g. `ProductService.GetProducts`), `payload` (required, JSON request body).
- **`grpc_list_services`** — List services available on a gRPC server. Parameters: `url` (required).

## Requirements

- Python 3.11+
- [uv](https://docs.astral.sh/uv/)
- [`grpcurl`](https://github.com/fullstorydev/grpcurl) on PATH

Install `grpcurl`:

**macOS (Homebrew)**
```bash
brew install grpcurl
```

**Linux**
```bash
# Debian/Ubuntu
sudo apt install grpcurl

# Or download the latest binary from GitHub releases
curl -sSL https://github.com/fullstorydev/grpcurl/releases/latest/download/grpcurl_linux_x86_64.tar.gz | tar -xz
sudo mv grpcurl /usr/local/bin/
```

**Windows (Scoop)**
```powershell
scoop install grpcurl
```

**Go (any platform)**
```bash
go install github.com/fullstorydev/grpcurl/cmd/grpcurl@latest
```

Verify the install:
```bash
grpcurl --version
```

## Install

The recommended way is via `uvx` — no separate install step needed:

```json
{
  "mcpServers": {
    "grpcurl": {
      "command": "uvx",
      "args": ["grpcurl-mcp"]
    }
  }
}
```

`uvx` fetches and runs the package from [PyPI](https://pypi.org/project/grpcurl-mcp/) automatically.

Or install explicitly with pip:

```bash
pip install grpcurl-mcp
```

## Claude Code setup

Run this command to register the server (one-time setup):

```bash
claude mcp add grpcurl -- uvx grpcurl-mcp
```

Or add it manually to your Claude Code MCP config (`~/.claude/settings.json` or project `.claude/settings.json`):

```json
{
  "mcpServers": {
    "grpcurl": {
      "command": "uvx",
      "args": ["grpcurl-mcp"]
    }
  }
}
```

## Cursor setup

Edit `~/.cursor/mcp.json` (global) or `.cursor/mcp.json` (project-level) and add:

```json
{
  "mcpServers": {
    "grpcurl": {
      "command": "uvx",
      "args": ["grpcurl-mcp"]
    }
  }
}
```

Then restart Cursor. Alternatively, use the UI: **Cursor Settings** → **Features** → **MCP** → add a new server with command `uvx` and arg `grpcurl-mcp`.

## Local development

From the project root:

```bash
uv sync
uv run python main.py
```

For debugging with HTTP transport:

```bash
MCP_TRANSPORT=http uv run python main.py
```

Then connect to `http://localhost:8000/mcp` with the [MCP Inspector](https://github.com/modelcontextprotocol/inspector).

## Example prompts

- **List available services:**  
  *"List gRPC services on `grpc.example.com:443`"*

- **Fetch products by SKU:**  
  *"Call `ProductsView.GetProductsById` on `grpc.example.com:443` with SKUs `["SKU-001", "SKU-002"]`"*

- **Run a query:**  
  *"Call `ExampleService.GetProducts` on `grpc.example.com:443` with payload `{"skus": ["SKU-001"]}`"*

## License

MIT
