gen-mcp: Zero-Code MCP Server Generation

Transform any API into an MCP server in seconds, not hours

⚠️ Early Preview: This is a research project in active development. APIs and features may change.

gen-mcp eliminates the complexity of building Model Context Protocol (MCP) servers. Instead of writing boilerplate code and learning protocol internals, simply describe your tools in a configuration file—gen-mcp handles the rest.

Perfect for:

• 🔌 API Developers - Expose existing REST APIs to AI assistants instantly
• 🤖 AI Engineers - Connect LLMs to external tools without custom server code
• 🛠️ DevOps Teams - Integrate legacy systems with modern AI workflows

✨ Key Features

• 🚀 Zero-Code Server Generation - Create MCP servers from simple YAML configs
• 📡 OpenAPI Auto-Conversion - Transform existing OpenAPI specs into MCP servers instantly
• 🔄 Real-Time Tool Exposure - HTTP endpoints become callable AI tools automatically
• 🛡️ Built-in Validation - Schema validation and type safety out of the box
• 🔐 Security Out of the Box - TLS encryption and OAuth/OIDC authentication built-in
• ⚡ Background Processing - Detached server mode with process management
• 🔧 Flexible Configuration - Fine-tune which endpoints to expose and how they behave

🚀 Quick Start

1. Install gen-mcp

Option A: Download Pre-built Binary

# Download from GitHub releases
# Visit: https://github.com/genmcp/gen-mcp/releases
# Or using curl (replace with latest version and platform):
curl -L https://github.com/genmcp/gen-mcp/releases/latest/download/genmcp-linux-amd64.zip -o genmcp-linux-amd64.zip
unzip genmcp-linux-amd64.zip
chmod +x genmcp-linux-amd64
sudo mv genmcp-linux-amd64 /usr/local/bin/genmcp

Verify the signed binary

You can cryptographically verify that the downloaded binaries (.zip files) are authentic and have not been tampered with. This process uses cosign to check the signature and certificate, which were generated securely during our automated build process.

Step 1: Install Cosign

You'll need the cosign command-line tool. Please see the Official Cosign Installation Guide.

Step 2: Verify the Binary

1. From the release page, download the signed bundle for your platform:

   • The bundle file (e.g., genmcp-linux-amd64.zip.bundle)

2. Run the cosign verify-blob-attestation command in your terminal.

   Example (for the Linux amd64 CLI):

     cosign verify-blob-attestation \
        --bundle genmcp-linux-amd64.zip.bundle \
        --certificate-identity-regexp "https://github.com/genmcp/gen-mcp/.*" \
        --certificate-oidc-issuer "https://token.actions.githubusercontent.com" \
        --new-bundle-format \
        genmcp-linux-amd64.zip
   

3.  If the signature is valid, `cosign` will contact the public Sigstore transparency log and print:
 ```
 Verified OK
 ```

**Option B: Build from Source**
```bash
# Clone and build
git clone https://github.com/genmcp/gen-mcp.git
cd gen-mcp

# Build CLI
make build-cli

# Add to PATH (recommended)
sudo mv genmcp /usr/local/bin

2. Choose Your Own Adventure

Option A: Convert Existing API

genmcp convert https://api.example.com/openapi.json
genmcp run

Option B: Create Custom Tools

# Create mcpfile.yaml with your tools (see documentation)
genmcp run

3. See It In Action

• 📹 HTTP Conversion Demo
• 📹 Ollama Integration Demo

📖 Documentation

• MCP File Format Guide - Learn to write custom tool configurations
• Server Config Guide - Configure server runtime settings
• Migration Guide - Migrate between GenMCP versions
• Examples Directory - Real-world integration examples

💻 Usage

Core Commands

Command	Description	Example
run	Start MCP server	genmcp run -f myapi.yaml
stop	Stop running server	genmcp stop
convert	OpenAPI → MCP conversion	genmcp convert api-spec.json
build	Build container image from mcpfile	genmcp build -f myapi.yaml --tag myapi:latest
version	Display version information	genmcp version

Starting Your Server

# Run in foreground (development)
genmcp run -f /path/to/mcpfile.yaml

# Run in background
genmcp run -d

# Auto-detect mcpfile.yaml in current directory
genmcp run

Converting Existing APIs

# From local OpenAPI file
genmcp convert ./api-spec.json

# From remote OpenAPI URL
genmcp convert https://api.example.com/openapi.json -o custom-name.yaml

# Petstore example
genmcp convert https://petstore.swagger.io/v2/swagger.json

Building Container Images

The build command packages your MCP server and mcpfile into a container image. By default, it builds multi-architecture images for broader platform support.

Binary Downloads: The build process automatically downloads the required server binaries from GitHub releases and caches them locally for reuse. Downloaded binaries are cryptographically verified using Sigstore to ensure authenticity and integrity.

Version Matching:

• Release builds: Download server binaries matching the CLI version (e.g., v0.1.0 downloads v0.1.0 server)
• Development builds: Automatically use latest release server binaries
• Custom version: Use --server-version flag to specify a specific server version

Requirements:

• Network access to download binaries from GitHub releases and query GitHub API
• No external dependencies required (verification is built into the CLI)

Offline Support:

• If download fails, automatically uses the latest cached version for that platform
• Warns when using cached fallback version
• Works completely offline once binaries are cached

Cache Management:

• Automatically keeps the last 3 versions per platform
• Older versions are cleaned up when downloading new binaries
• Manual cleanup: remove ~/.cache/genmcp/binaries/ (Linux), ~/Library/Caches/.genmcp/binaries/ (macOS), or %LOCALAPPDATA%\.genmcp\binaries\ (Windows)

Multi-Architecture Build (Default)

When no --platform is specified, builds for both linux/amd64 and linux/arm64:

# Build and push multi-arch image to registry
genmcp build --tag registry.example.com/myapp:v1.0.0 --push

# Build multi-arch locally
genmcp build --tag myapp:latest  # Creates: myapp:latest-linux-amd64, myapp:latest-linux-arm64

Single-Platform Build

For faster iteration during development, specify a single platform:

# Build for specific platform
genmcp build --tag myapp:dev --platform linux/amd64

# Build for ARM64
genmcp build --tag myapp:latest --platform linux/arm64

Additional Options

# Custom base image
genmcp build --tag myapp:latest \
  --base-image registry.access.redhat.com/ubi9/ubi-minimal:latest

# Specify mcpfile location
genmcp build --tag myapp:latest -f path/to/mcpfile.yaml

# Use specific server version
genmcp build --tag myapp:latest --server-version v0.1.0

# Full example with all options
genmcp build \
  --tag myregistry.io/myapp:v1.0.0 \
  --file ./custom-mcpfile.yaml \
  --platform linux/amd64 \
  --server-version v0.1.1 \
  --push

Binary Cache Location: Downloaded binaries are cached in your user cache directory and reused across builds:

• Linux: ~/.cache/genmcp/binaries/
• macOS: ~/Library/Caches/.genmcp/binaries/
• Windows: %LOCALAPPDATA%\.genmcp\binaries\

The cache stores version-platform pairs and validates checksums on each use.

Note: When building multi-arch locally, Docker daemon doesn't support manifest lists, so each platform is saved with a platform-specific tag (e.g., myapp:latest-linux-amd64). Additionally, the original tag (myapp:latest) is saved with your host platform's image if available, otherwise the first built platform. When pushing to a registry with --push, a proper multi-arch manifest list is created.

Converting CLI (Experimental)

Instead of manually writing an MCP file for a CLI, you can use an LLM to generate a genmcp-compatible mcpfile.yaml.

# Set OpenAI endpoint configurations
export MODEL_BASE_URL='https://HOST:PORT/v1' # OpenAI Base URL (v1 endpoint)
export MODEL_KEY='' # OpenAI Access Token
export MODEL_NAME=''  # OpenAI Model Name

# Run gen-mcp convert-cli to generate mcpfile.yaml
MODEL_BASE_URL=$MODEL_BASE_URL MODEL_KEY=$MODEL_KEY MODEL_NAME=$MODEL_NAME genmcp convert-cli "podman images"

# Start mcpserver with generated mcpfile.yaml 
genmcp run

Managing Running Servers

# Stop server (uses mcpfile.yaml to find process)
genmcp stop

# Stop specific server
genmcp stop -f /path/to/mcpfile.yaml

💡 Authoring GenMCP config files with auto complete

To improve the development experience and prevent configuration errors, this project includes JSON schemas for both GenMCP config file formats. These schemas enable validation, autocompletion, and inline documentation in compatible code editors like Visual Studio Code, helping you write valid configuration files faster.

To make use of the schemas, add a yaml-language-server comment at the top of your files:

MCP File:

# yaml-language-server: $schema=https://raw.githubusercontent.com/genmcp/gen-mcp/refs/heads/main/specs/mcpfile-schema.json
kind: MCPToolDefinitions
schemaVersion: "0.2.0"
name: ...

Server Config File:

# yaml-language-server: $schema=https://raw.githubusercontent.com/genmcp/gen-mcp/refs/heads/main/specs/mcpserver-schema.json
kind: MCPServerConfig
schemaVersion: "0.2.0"
runtime: ...

Intellij IDEs support JSON schema validation natively.

VS Code requires the installation of the YAML extension by Red Hat.

📚 Examples & Tutorials

🤖 Ollama Integration

📹 Watch Demo | View Code

Connect local language models to MCP Clients with gen-mcp in two ways: by wrapping the Ollama CLI, and by wrapping the Ollama http endpoints.

Features:

• ✅ HTTP REST API integration
• ✅ CLI command execution
• ✅ Model management tools

🔗 HTTP API Conversion

📹 Watch Demo | View Code

Transform any REST API into MCP tools automatically:

# 1. Convert OpenAPI spec
genmcp convert http://localhost:9090/openapi.json

# 2. Run the generated MCP server
genmcp run

Demonstrates:

• 🔄 Automatic OpenAPI → MCP conversion
• 🛠️ Path parameter substitution (/features/{id})
• 📊 Schema validation and type safety
• 🎯 Selective endpoint exposure

🔌 gRPC Service Integration

View Demo Repository

Expose existing gRPC services to LLMs without modifying service code:

Architecture:

• Uses gRPC-Gateway to create an HTTP/JSON proxy
• Exposes the HTTP proxy as MCP tools via gen-mcp
• Works with any gRPC service using only .proto definitions

Perfect for:

• 🏢 Integrating legacy gRPC services with AI workflows
• 🔄 Bridging binary gRPC with JSON-based LLM interfaces
• 🚀 Getting started before native gRPC support arrives

Note: This is a workaround pattern until gen-mcp adds native gRPC support.

---

🤝 Contributing

We welcome contributions! This is an early-stage research project with lots of room for improvement.

Join the Community

Have questions or want to discuss gen-mcp? Join our Discord community:

Join Discord - Connect with other users, share ideas, and get help

Development Setup

git clone https://github.com/genmcp/gen-mcp.git
cd gen-mcp
go test ./...

# Build local binary
make build-cli

📄 License

Apache 2.0 License - see LICENSE file for details.

🔗 Links

• Model Context Protocol - Official MCP documentation
• MCP File Format - Tool definitions reference
• Server Config - Server runtime configuration reference
• Migration Guide - Migrate between GenMCP versions
• Examples - Real-world integration examples
• gRPC Integration Demo - Pattern for exposing gRPC services via HTTP proxy

---