https://github.com/acunningham-ship-it/mcpforge
Auto-generate Model Context Protocol (MCP) servers from any API in seconds — works with Claude Desktop, Cursor, and any MCP-compatible AI tool
https://github.com/acunningham-ship-it/mcpforge
ai-tools claude code-generation developer-tools fastmcp llm mcp model-context-protocol ollama openapi
Last synced: 18 days ago
JSON representation
Auto-generate Model Context Protocol (MCP) servers from any API in seconds — works with Claude Desktop, Cursor, and any MCP-compatible AI tool
- Host: GitHub
- URL: https://github.com/acunningham-ship-it/mcpforge
- Owner: acunningham-ship-it
- License: mit
- Created: 2026-04-08T03:54:46.000Z (3 months ago)
- Default Branch: main
- Last Pushed: 2026-04-08T04:15:10.000Z (3 months ago)
- Last Synced: 2026-04-08T06:07:43.630Z (3 months ago)
- Topics: ai-tools, claude, code-generation, developer-tools, fastmcp, llm, mcp, model-context-protocol, ollama, openapi
- Language: Python
- Homepage: https://acunningham-ship-it.github.io/mcpforge
- Size: 56.6 KB
- Stars: 0
- Watchers: 0
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# MCPForge ⚡
**Auto-generate [Model Context Protocol (MCP)](https://modelcontextprotocol.io) servers from any API in seconds.**
Point MCPForge at an OpenAPI spec, get a ready-to-run Python MCP server that works with Claude Desktop, Cursor, Zed, and any MCP-compatible AI tool.
[](LICENSE)
[](https://www.python.org/)
[](https://modelcontextprotocol.io)
[](https://ollama.com)
**[Website](https://acunningham-ship-it.github.io/mcpforge)** · **[GitHub](https://github.com/acunningham-ship-it/mcpforge)**
---
## Why MCPForge?
The [Model Context Protocol](https://modelcontextprotocol.io) lets AI assistants use tools — but writing MCP servers by hand is tedious boilerplate. MCPForge generates them automatically from existing API documentation.
```bash
# Before MCPForge: hand-write 200+ lines of MCP boilerplate
# After MCPForge:
mcpforge generate https://api.github.com/openapi.json
# → github_mcp.py (32 tools, ready to run)
```
---
## Quick Start
```bash
pip install mcpforge
# Generate from an OpenAPI spec URL
mcpforge generate https://petstore.swagger.io/v2/swagger.json
# Run the generated MCP server
python petstore_mcp.py
# Or try a built-in demo
mcpforge demo github
```
**That's it.** Add the server to Claude Desktop and your AI can now use the Petstore API.
---
## Installation
```bash
pip install mcpforge
```
Or from source:
```bash
git clone https://github.com/acunningham-ship-it/mcpforge.git
cd mcpforge
pip install -e .
```
**Requirements:**
- Python 3.10+
- [Ollama](https://ollama.com) (optional — for AI-enhanced descriptions)
---
## CLI Reference
```bash
# Generate MCP server from OpenAPI URL
mcpforge generate https://api.example.com/openapi.json
# Generate from local file
mcpforge generate ./my-api-spec.yaml
# Specify output file
mcpforge generate ./spec.yaml --output my_server.py
# Use Ollama to enhance tool descriptions
mcpforge generate ./spec.yaml --enhance
# List available examples
mcpforge examples
# Run a demo MCP server
mcpforge demo github
mcpforge demo weather
mcpforge demo calculator
```
---
## How It Works
### 1. Parse
MCPForge parses OpenAPI 3.0 / Swagger 2.0 specs — from URLs, local files, or raw YAML/JSON.
For each endpoint, it extracts:
- Path, method, operationId
- Parameters (path, query, header, body)
- Summary and description
- Authentication requirements (Bearer, API key, Basic)
- Response schema
### 2. Enhance (optional)
If Ollama is running locally, MCPForge uses a local model to:
- Rewrite terse technical descriptions into clear, AI-friendly tool descriptions
- Identify the most important parameters
- Generate usage examples
This improves how well AI assistants understand what each tool does.
### 3. Generate
Produces a single self-contained Python file using the official [MCP Python SDK](https://github.com/modelcontextprotocol/python-sdk):
```python
#!/usr/bin/env python3
"""MCP server for GitHub API — auto-generated by MCPForge"""
import os
import httpx
from mcp.server.fastmcp import FastMCP
mcp = FastMCP("GitHub API")
BASE_URL = "https://api.github.com"
GITHUB_TOKEN = os.environ.get("GITHUB_TOKEN", "")
@mcp.tool()
def list_repos(owner: str, per_page: int = 30) -> dict:
"""List public repositories for a GitHub user."""
headers = {"Authorization": f"Bearer {GITHUB_TOKEN}"} if GITHUB_TOKEN else {}
resp = httpx.get(f"{BASE_URL}/users/{owner}/repos", params={"per_page": per_page}, headers=headers)
resp.raise_for_status()
return resp.json()
# ... more tools ...
if __name__ == "__main__":
mcp.run()
```
### 4. Validate
Checks the generated file for syntax errors and verifies MCP structure before writing to disk.
---
## Adding to Claude Desktop
Edit `~/Library/Application Support/Claude/claude_desktop_config.json`:
```json
{
"mcpServers": {
"github": {
"command": "python",
"args": ["/path/to/github_mcp.py"],
"env": {
"GITHUB_TOKEN": "your-github-token"
}
}
}
}
```
Restart Claude Desktop. Your AI can now use the GitHub API.
---
## Web UI
MCPForge includes a web interface for generating servers without the CLI:
```bash
mcpforge serve
# Open http://localhost:8000
```
Paste any OpenAPI spec URL, click Generate, copy the result.
---
## Built-in Examples
| Example | Description | Tools |
|---------|-------------|-------|
| `github` | GitHub public API | list_repos, get_repo, search_repos, list_issues |
| `weather` | wttr.in weather (no key needed) | get_weather, get_forecast |
| `calculator` | Math operations | add, subtract, multiply, divide, calculate |
```bash
# Run any example immediately
mcpforge demo github
mcpforge demo weather
mcpforge demo calculator
```
---
## REST API
MCPForge exposes a REST API for programmatic generation:
```bash
# Start the API server
mcpforge serve
# Generate via API
curl -X POST http://localhost:8000/api/generate \
-H "Content-Type: application/json" \
-d '{"spec_url": "https://petstore.swagger.io/v2/swagger.json", "enhance": false}'
# Response: {"server_code": "...", "tools": [...], "api_name": "Petstore"}
```
---
## Configuration
MCPForge works with zero configuration. Optionally create `mcpforge.yaml`:
```yaml
ollama_url: "http://localhost:11434"
enhance_model: "qwen2.5:7b" # Model to use for description enhancement
max_tools: 50 # Max tools per generated server
output_dir: "./generated" # Default output directory
```
---
## Architecture
```
mcpforge/
├── mcpforge/ # Core library
│ ├── parser.py # OpenAPI 3.0 / Swagger 2.0 parser
│ ├── generator.py # MCP server code generator
│ ├── enhancer.py # Ollama description enhancer
│ └── validator.py # Generated code validator
├── cli/main.py # Typer CLI (mcpforge command)
├── api/main.py # FastAPI web API + UI
├── examples/ # Built-in MCP server examples
│ ├── github_mcp.py
│ ├── weather_mcp.py
│ └── calculator_mcp.py
├── tests/ # pytest test suite
└── docs/ # GitHub Pages website
```
---
## Supported Features
| Feature | Status |
|---------|--------|
| OpenAPI 3.0 | ✅ |
| Swagger 2.0 | ✅ |
| Bearer auth | ✅ |
| API key auth | ✅ |
| Path parameters | ✅ |
| Query parameters | ✅ |
| Request body | ✅ |
| Ollama enhancement | ✅ optional |
| Syntax validation | ✅ |
| Web UI | ✅ |
| Docker | ✅ |
---
## MCP Resources
- [Model Context Protocol](https://modelcontextprotocol.io) — Official MCP site
- [MCP Python SDK](https://github.com/modelcontextprotocol/python-sdk) — The SDK MCPForge uses
- [MCP Servers](https://github.com/modelcontextprotocol/servers) — Community servers
- [Claude Desktop MCP Guide](https://docs.anthropic.com/claude/docs/mcp) — Connect to Claude
---
## License
MIT — see [LICENSE](LICENSE)
---
Built with Python, FastAPI, and the [MCP Python SDK](https://github.com/modelcontextprotocol/python-sdk).