mcpizer

Convert any REST API or gRPC service into MCP tools for AI assistants

2 stars GoOthers Updated Jul 8, 2026

api-bridgegogrpcmcpmodel-context-protocolopenapi

Documentation

MCPizer

MCPizer lets your AI assistant (Claude, VS Code, etc.) call any REST API or gRPC service by automatically converting their schemas into MCP (Model Context Protocol) tools.

Key Features:

🚀 GitHub integration - fetch schemas directly with `github://` URLs
📄 .proto file support - use gRPC without reflection enabled
🔐 Private repo support - automatic authentication via `gh` CLI
🌐 Connect-RPC support - HTTP/JSON and gRPC modes
🔧 Auto-discovery - finds OpenAPI/Swagger endpoints automatically

What is MCPizer?

MCPizer is a server that:

Auto-discovers API schemas from your services (OpenAPI/Swagger, gRPC reflection, .proto files)
Converts them into tools your AI can use
Handles all the API calls with proper types and error handling

Works with any framework that exposes OpenAPI schemas (FastAPI, Spring Boot, Express, etc.) or gRPC services (with reflection or .proto files). No code changes needed in your APIs - just point MCPizer at them!

How it Works

mermaid

sequenceDiagram
    participant AI as AI Assistant(Claude/VS Code)
    participant MCP as MCPizer
    participant API as Your APIs(REST/gRPC)
    
    Note over AI,API: Initial Setup
    MCP->>API: Auto-discover schemas
    API-->>MCP: OpenAPI/gRPC reflection
    MCP->>MCP: Convert to MCP tools
    
    Note over AI,API: Runtime Usage
    AI->>MCP: List available tools
    MCP-->>AI: Tools from all APIs
    AI->>MCP: Call tool "create_user"
    MCP->>API: POST /users
    API-->>MCP: {"id": 123, "name": "Alice"}
    MCP-->>AI: Tool result

Architecture Overview

mermaid

graph TB
    subgraph "AI Assistants"
        Claude[Claude Desktop]
        VSCode[VS Code Extensions]
        Other[Other MCP Clients]
    end
    
    subgraph "MCPizer"
        Transport{Transport Layer}
        Discovery[Schema Discovery]
        Converter[Tool Converter]
        Invoker[API Invoker]
        
        Transport -->|STDIO/SSE| Discovery
        Discovery --> Converter
        Converter --> Invoker
    end
    
    subgraph "Your APIs"
        FastAPI[FastAPIAuto-discovery]
        Spring[Spring BootAuto-discovery]
        gRPC[gRPC ServicesReflection/.proto]
        Custom[Custom APIsDirect schema URL]
    end
    
    Claude --> Transport
    VSCode --> Transport
    Other --> Transport
    
    Invoker --> FastAPI
    Invoker --> Spring
    Invoker --> gRPC
    Invoker --> Custom
    
    style MCPizer fill:#e1f5e1
    style Transport fill:#fff2cc
    style Discovery fill:#fff2cc
    style Converter fill:#fff2cc
    style Invoker fill:#fff2cc

Installation

bash

# Install MCPizer
go install github.com/i2y/mcpizer/cmd/mcpizer@latest

# Verify installation
mcpizer --help

Usage Examples

bash

# Use default config file (configs/mcpizer.yaml)
mcpizer

# Specify config file via command line (highest priority)
mcpizer -config=/path/to/config.yaml

# Use GitHub-hosted config
mcpizer -config=github://myorg/configs/mcpizer-prod.yaml

# Or via environment variable
export MCPIZER_CONFIG_FILE=/path/to/config.yaml
mcpizer

# STDIO mode with custom config
mcpizer -transport=stdio -config=./my-config.yaml

> Note: Make sure `$GOPATH/bin` is in your PATH. If not installed, install Go first.

Quick Start

Step 1: Configure Your APIs

Create a config file with your API endpoints:

yaml

schema_sources:
  # Production APIs with HTTPS
  - https://api.mycompany.com              # Auto-discovers OpenAPI
  - https://api.example.com/openapi.json   # Direct schema URL
  
  # GitHub-hosted schemas (NEW: use github:// URLs)
  - github://myorg/api-specs/main/user-api.yaml     # Uses gh CLI auth
  - github://OAI/OpenAPI-Specification/examples/v3.0/petstore.yaml@master
  - https://raw.githubusercontent.com/myorg/api-specs/main/user-api.yaml  # Direct URL also works
  
  # Internal services (FastAPI, Spring Boot, etc.)
  - http://my-fastapi-app:8000     # Auto-discovers at /openapi.json, /docs
  - http://spring-service:8080     # Auto-discovers at /v3/api-docs
  
  # gRPC services (must have reflection enabled)
  - grpc://my-grpc-service:50051
  
  # gRPC with .proto files (NEW! - no reflection needed)
  - url: https://raw.githubusercontent.com/myorg/protos/main/service.proto
    server: grpc://production.example.com:50051
  
  # Or use github:// for private repos (uses gh CLI)
  - url: github://myorg/protos/service.proto@main
    server: grpc://production.example.com:50051
  
  # Connect-RPC services (NEW!)
  # If the service supports gRPC reflection:
  - grpc://connect.example.com:50051
  
  # Connect-RPC with HTTP/JSON mode:
  - url: github://connectrpc/examples/eliza/eliza.proto
    server: https://demo.connectrpc.com
    type: connect
    mode: http  # Use HTTP/JSON for easier debugging
  
  # Local development
  - http://localhost:3000
  - grpc://localhost:50052
  
  # Public test APIs
  - https://petstore3.swagger.io/api/v3/openapi.json
  - grpc://grpcb.in:9000

Step 2: Choose Your Transport Mode

MCPizer supports two transport modes:

📝 STDIO Mode (for clients that manage process lifecycle)

Used by clients that start MCPizer as a subprocess and communicate via standard input/output.

Example: Claude Desktop

Add to your configuration file:

macOS: `~/Library/Application Support/Claude/claude_desktop_config.json`
Windows: `%APPDATA%\Claude\claude_desktop_config.json`
Linux: `~/.config/Claude/claude_desktop_config.json`

json

{
  "mcpServers": {
    "mcpizer": {
      "command": "mcpizer",
      "args": ["-transport=stdio", "-config=/path/to/your/config.yaml"]
    }
  }
}

The client will start MCPizer automatically when needed.

🌐 SSE Mode (Server-Sent Events over HTTP)

Used by clients that connect to a running MCPizer server via HTTP.

bash

# Start MCPizer server (if your client doesn't start it automatically)
mcpizer

# Server runs at http://localhost:8080/sse

Configure your MCP client to connect to `http://localhost:8080/sse`

Note: Some clients may start the server automatically, while others require manual startup.

🧪 For Testing/Development

bash

# Quick test - list available tools
mcpizer -transport=stdio http://your-api:8000"] 
    
    Try1["/openapi.jsonFastAPI default"]
    Try2["/docs/openapi.jsonFastAPI alt"]
    Try3["/swagger.jsonSwagger 2.0"]
    Try4["/v3/api-docsSpring Boot"]
    Try5["...more paths..."]
    
    Found["✓ Schema found!Parse and convert"]
    NotFound["✗ Not foundTry direct URL"]
    
    Start --> Try1
    Try1 -->|404| Try2
    Try2 -->|404| Try3
    Try3 -->|404| Try4
    Try4 -->|404| Try5
    
    Try1 -->|200| Found
    Try2 -->|200| Found
    Try3 -->|200| Found
    Try4 -->|200| Found
    
    Try5 -->|All fail| NotFound
    
    style Start fill:#e3f2fd
    style Found fill:#c8e6c9
    style NotFound fill:#ffcdd2

Supported frameworks:

FastAPI: `/openapi.json`, `/docs/openapi.json`
Spring Boot: `/v3/api-docs`, `/swagger-ui/swagger.json`
Express/NestJS: `/api-docs`, `/swagger.json`
Rails: `/api/v1/swagger.json`, `/apidocs`
See full list

gRPC Services

yaml

schema_sources:
  # Using gRPC reflection (requires reflection enabled on server)
  - grpc://your-grpc-host:50051     # Your service
  - grpc://grpcb.in:9000            # Public test service
  
  # Using .proto files (NEW! - no reflection needed)
  - url: https://raw.githubusercontent.com/grpc/grpc-go/master/examples/helloworld/helloworld/helloworld.proto
    server: grpc://production.example.com:50051
  
  # Private GitHub .proto files (uses gh CLI authentication)
  - url: github://myorg/protos/user-service.proto
    server: grpc://user-service:50051
  
  # With specific branch/tag
  - url: github://grpc/grpc-go/examples/helloworld/helloworld/helloworld.proto@v1.65.0
    server: grpc://production.example.com:50051

Option 1: gRPC Reflection (requires reflection enabled):

// In your gRPC server
import "google.golang.org/grpc/reflection"
reflection.Register(grpcServer)

Option 2: .proto Files (NEW! - more secure, no reflection needed):

Host your `.proto` files anywhere (GitHub, S3, CDN, etc.)
GitHub URLs (`github://`) automatically use `gh` CLI authentication
Specify the `server` endpoint separately
Perfect for production where reflection is disabled
Allows schema versioning and CI/CD validation

For alternative reflection implementations, see:

connectrpc/grpcreflect-go Connect-Go's reflection implementation

Local Files

yaml

schema_sources:
  - ./api-spec.json
  - /path/to/openapi.yaml

GitHub Integration (NEW!)

MCPizer can fetch schemas directly from GitHub repositories using the `gh` CLI tool - including both OpenAPI and .proto files:

yaml

schema_sources:
  # OpenAPI schemas from GitHub
  - github://owner/repo/path/to/openapi.yaml
  - github://microsoft/api-guidelines/graph/openapi.yaml@v1.0
  
  # .proto files from GitHub (NEW!)
  - url: github://grpc/grpc-go/examples/helloworld/helloworld/helloworld.proto@master
    server: grpc://production.example.com:50051
  
  # Private repositories (uses gh CLI authentication)
  - github://myorg/private-apis/user-api.yaml
  - url: github://myorg/private-protos/service.proto@v2.0
    server: grpc://internal-service:50051
  
  # Load MCPizer config itself from GitHub!
  # Set MCPIZER_CONFIG_FILE=github://myorg/configs/mcpizer.yaml

Benefits:

✅ Works with private repositories (uses `gh` authentication)
✅ Specify branches/tags with `@ref` syntax
✅ No need to manage raw GitHub URLs or tokens
✅ Supports both OpenAPI and .proto files
✅ Config files can also be stored in GitHub

Requirements:

Install GitHub CLI: `brew install gh` (macOS) or see docs
Authenticate: `gh auth login`

Environment Variables

Variable	Default	When to use
`MCPIZER_CONFIG_FILE`	`~/.mcpizer.yaml`	Different config per environmentCan be `github://` URL!
`MCPIZER_LOG_LEVEL`	`info`	Set to `debug` for troubleshooting
`MCPIZER_LOG_FILE`	`/tmp/mcpizer.log`	Change log location (STDIO mode)
`MCPIZER_LISTEN_ADDR`	`:8080`	Change port (SSE mode)
`MCPIZER_HTTP_CLIENT_TIMEOUT`	`30s`	Slow APIs need more time

Common Scenarios

"I want Claude to use my local FastAPI app"

bash

# 1. Your FastAPI runs on port 8000
python -m uvicorn main:app

# 2. Install MCPizer
go install github.com/i2y/mcpizer/cmd/mcpizer@latest

# 3. Configure (~/.mcpizer.yaml)
echo "schema_sources:\n  - http://localhost:8000" > ~/.mcpizer.yaml

# 4. Add to Claude Desktop config and restart
# Now ask Claude: "What endpoints are available?"

"I want to test if MCPizer sees my API"

bash

# Quick check - what tools are available?
mcpizer -transport=stdio • Try direct schema URL• Check debug logs |
| "Connection refused" | • Wrong port?• Check if API is running• Firewall blocking? |
| "String should have at most 64 characters" | Update MCPizer - this is fixed in latest version |
| gRPC "connection refused" | • Enable reflection in your gRPC server• Check with `grpcurl`• Or use .proto file approach instead |
| "Schema not found at base URL" | • Specify exact schema path• Check if API exposes OpenAPI |
| ".proto file missing server" | • Add `server: grpc://host:port` to your config• Required for .proto files |

## Examples

### Complete Flow Example

Here's how MCPizer works with a FastAPI service:

flowchart LR

subgraph "Your FastAPI App"

API[FastAPI ServicePort 8000]

Schema["/openapi.jsonAuto-generated"]

API --> Schema

end

subgraph "MCPizer Config"

Config["~/.mcpizer.yamlschema_sources:http://my-fastapi:8000"]

end

subgraph "MCPizer Process"

Discover["(1) Discover schemaat /openapi.json"]

Convert["(2) Convert endpointsto MCP tools"]

Discover --> Convert

Convert --> Register

end

subgraph "AI Assistant"

List["List tools:• get_item• create_item• update_item"]

Call["Call: get_item{item_id: 123}"]

Result["Result:{id: 123, name: 'Test'}"]

List --> Call

Call --> Result

end

Config --> Discover

Schema --> Discover

Call -->	HTTP GET /items/123	API
API -->	JSON Response	Result

style API fill:#e8f4fd

style Config fill:#fff4e6

style Register fill:#e8f5e9

style Result fill:#f3e5f5

code

### FastAPI Example

main.py

from fastapi import FastAPI

app = FastAPI()

@app.get("/items/{item_id}")

def get_item(item_id: int, q: str = None):

return {"item_id": item_id, "q": q}

MCPizer auto-discovers at http://localhost:8000/openapi.json

code

### gRPC Example

**Option 1: Using Reflection**

// Enable reflection for MCPizer

import "google.golang.org/grpc/reflection"

func main() {

s := grpc.NewServer()

pb.RegisterYourServiceServer(s, &server{})

reflection.Register(s) // This line enables MCPizer support

s.Serve(lis)

}

code

**Option 2: Using .proto Files (Recommended for Production)**

config.yaml

schema_sources:

# Your .proto file in version control

server: grpc://user-service.prod.example.com:443

# Multiple environments, same schema

server: grpc://user-service.staging.example.com:443

code

Benefits:
- ✅ No reflection needed in production
- ✅ Version-controlled schemas
- ✅ CI/CD can validate schemas
- ✅ Same .proto for multiple environments

## Development

Run tests

go test ./...

Run integration tests (requires internet connection)

go test -tags=integration ./...

Build locally

go build -o mcpizer ./cmd/mcpizer

Run with example services (includes Petstore, gRPC test service, Jaeger)

docker compose up

Run individual examples

cd examples/fastapi && pip install -r requirements.txt && python main.py

code

See [examples/](examples/) for more complete examples:
- [proto-config.yaml](examples/proto-config.yaml) - Using .proto files with multiple environments
- [fastapi/](examples/fastapi/) - FastAPI integration example
- [grpc-service/](examples/grpc-service/) - gRPC service with reflection

## Contributing

Contributions welcome! Please:
1. Check existing issues first
2. Fork and create a feature branch
3. Add tests for new functionality
4. Submit a PR

## License

MIT - see [LICENSE](LICENSE)

Frequently asked questions

What is mcpizer?

mcpizer is Convert any REST API or gRPC service into MCP tools for AI assistants

How do I install mcpizer?

Open the GitHub repository and follow its README. Most MCP servers are added to your client's MCP config, then called by your agent.

Is mcpizer open source?

Yes — it is hosted on GitHub at https://github.com/i2y/mcpizer and has 2 stars.

Related MCP tools

kubeshark

eBPF-powered network observability for Kubernetes. Indexes L4/L7 traffic with full K8s context, decrypts TLS without keys. Queryable by AI agents via MCP and humans via dashboard.

12,068 Go

kubernetesgolangrest+17

radar

The missing open-source Kubernetes UI with a built-in MCP server for AI agents. See what's broken, why, and what changed. Issues, Topology, event timeline, Helm, GitOps, live service traffic, and cluster audits - all in one Go binary.

3,246 Go

argocdcloud-nativegitops+17