{"id":50891458,"url":"https://github.com/acunningham-ship-it/mcpforge","last_synced_at":"2026-06-15T21:02:46.077Z","repository":{"id":349913490,"uuid":"1204489519","full_name":"acunningham-ship-it/mcpforge","owner":"acunningham-ship-it","description":"Auto-generate Model Context Protocol (MCP) servers from any API in seconds — works with Claude Desktop, Cursor, and any MCP-compatible AI tool","archived":false,"fork":false,"pushed_at":"2026-04-08T04:15:10.000Z","size":58,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-04-08T06:07:43.630Z","etag":null,"topics":["ai-tools","claude","code-generation","developer-tools","fastmcp","llm","mcp","model-context-protocol","ollama","openapi"],"latest_commit_sha":null,"homepage":"https://acunningham-ship-it.github.io/mcpforge","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/acunningham-ship-it.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-04-08T03:54:46.000Z","updated_at":"2026-04-08T04:15:18.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/acunningham-ship-it/mcpforge","commit_stats":null,"previous_names":["acunningham-ship-it/mcpforge"],"tags_count":1,"template":false,"template_full_name":null,"purl":"pkg:github/acunningham-ship-it/mcpforge","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/acunningham-ship-it%2Fmcpforge","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/acunningham-ship-it%2Fmcpforge/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/acunningham-ship-it%2Fmcpforge/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/acunningham-ship-it%2Fmcpforge/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/acunningham-ship-it","download_url":"https://codeload.github.com/acunningham-ship-it/mcpforge/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/acunningham-ship-it%2Fmcpforge/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":34379915,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-06-15T02:00:07.085Z","response_time":63,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["ai-tools","claude","code-generation","developer-tools","fastmcp","llm","mcp","model-context-protocol","ollama","openapi"],"created_at":"2026-06-15T21:02:45.225Z","updated_at":"2026-06-15T21:02:46.068Z","avatar_url":"https://github.com/acunningham-ship-it.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# MCPForge ⚡\n\n**Auto-generate [Model Context Protocol (MCP)](https://modelcontextprotocol.io) servers from any API in seconds.**\n\nPoint 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.\n\n[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)\n[![Python 3.10+](https://img.shields.io/badge/python-3.10+-blue.svg)](https://www.python.org/)\n[![MCP](https://img.shields.io/badge/MCP-1.0-purple.svg)](https://modelcontextprotocol.io)\n[![Ollama](https://img.shields.io/badge/Ollama-optional-green.svg)](https://ollama.com)\n\n**[Website](https://acunningham-ship-it.github.io/mcpforge)** · **[GitHub](https://github.com/acunningham-ship-it/mcpforge)**\n\n---\n\n## Why MCPForge?\n\nThe [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.\n\n```bash\n# Before MCPForge: hand-write 200+ lines of MCP boilerplate\n# After MCPForge:\nmcpforge generate https://api.github.com/openapi.json\n# → github_mcp.py (32 tools, ready to run)\n```\n\n---\n\n## Quick Start\n\n```bash\npip install mcpforge\n\n# Generate from an OpenAPI spec URL\nmcpforge generate https://petstore.swagger.io/v2/swagger.json\n\n# Run the generated MCP server\npython petstore_mcp.py\n\n# Or try a built-in demo\nmcpforge demo github\n```\n\n**That's it.** Add the server to Claude Desktop and your AI can now use the Petstore API.\n\n---\n\n## Installation\n\n```bash\npip install mcpforge\n```\n\nOr from source:\n```bash\ngit clone https://github.com/acunningham-ship-it/mcpforge.git\ncd mcpforge\npip install -e .\n```\n\n**Requirements:**\n- Python 3.10+\n- [Ollama](https://ollama.com) (optional — for AI-enhanced descriptions)\n\n---\n\n## CLI Reference\n\n```bash\n# Generate MCP server from OpenAPI URL\nmcpforge generate https://api.example.com/openapi.json\n\n# Generate from local file\nmcpforge generate ./my-api-spec.yaml\n\n# Specify output file\nmcpforge generate ./spec.yaml --output my_server.py\n\n# Use Ollama to enhance tool descriptions\nmcpforge generate ./spec.yaml --enhance\n\n# List available examples\nmcpforge examples\n\n# Run a demo MCP server\nmcpforge demo github\nmcpforge demo weather\nmcpforge demo calculator\n```\n\n---\n\n## How It Works\n\n### 1. Parse\nMCPForge parses OpenAPI 3.0 / Swagger 2.0 specs — from URLs, local files, or raw YAML/JSON.\n\nFor each endpoint, it extracts:\n- Path, method, operationId\n- Parameters (path, query, header, body)\n- Summary and description\n- Authentication requirements (Bearer, API key, Basic)\n- Response schema\n\n### 2. Enhance (optional)\nIf Ollama is running locally, MCPForge uses a local model to:\n- Rewrite terse technical descriptions into clear, AI-friendly tool descriptions\n- Identify the most important parameters\n- Generate usage examples\n\nThis improves how well AI assistants understand what each tool does.\n\n### 3. Generate\nProduces a single self-contained Python file using the official [MCP Python SDK](https://github.com/modelcontextprotocol/python-sdk):\n\n```python\n#!/usr/bin/env python3\n\"\"\"MCP server for GitHub API — auto-generated by MCPForge\"\"\"\n\nimport os\nimport httpx\nfrom mcp.server.fastmcp import FastMCP\n\nmcp = FastMCP(\"GitHub API\")\nBASE_URL = \"https://api.github.com\"\nGITHUB_TOKEN = os.environ.get(\"GITHUB_TOKEN\", \"\")\n\n@mcp.tool()\ndef list_repos(owner: str, per_page: int = 30) -\u003e dict:\n    \"\"\"List public repositories for a GitHub user.\"\"\"\n    headers = {\"Authorization\": f\"Bearer {GITHUB_TOKEN}\"} if GITHUB_TOKEN else {}\n    resp = httpx.get(f\"{BASE_URL}/users/{owner}/repos\", params={\"per_page\": per_page}, headers=headers)\n    resp.raise_for_status()\n    return resp.json()\n\n# ... more tools ...\n\nif __name__ == \"__main__\":\n    mcp.run()\n```\n\n### 4. Validate\nChecks the generated file for syntax errors and verifies MCP structure before writing to disk.\n\n---\n\n## Adding to Claude Desktop\n\nEdit `~/Library/Application Support/Claude/claude_desktop_config.json`:\n\n```json\n{\n  \"mcpServers\": {\n    \"github\": {\n      \"command\": \"python\",\n      \"args\": [\"/path/to/github_mcp.py\"],\n      \"env\": {\n        \"GITHUB_TOKEN\": \"your-github-token\"\n      }\n    }\n  }\n}\n```\n\nRestart Claude Desktop. Your AI can now use the GitHub API.\n\n---\n\n## Web UI\n\nMCPForge includes a web interface for generating servers without the CLI:\n\n```bash\nmcpforge serve\n# Open http://localhost:8000\n```\n\nPaste any OpenAPI spec URL, click Generate, copy the result.\n\n---\n\n## Built-in Examples\n\n| Example | Description | Tools |\n|---------|-------------|-------|\n| `github` | GitHub public API | list_repos, get_repo, search_repos, list_issues |\n| `weather` | wttr.in weather (no key needed) | get_weather, get_forecast |\n| `calculator` | Math operations | add, subtract, multiply, divide, calculate |\n\n```bash\n# Run any example immediately\nmcpforge demo github\nmcpforge demo weather\nmcpforge demo calculator\n```\n\n---\n\n## REST API\n\nMCPForge exposes a REST API for programmatic generation:\n\n```bash\n# Start the API server\nmcpforge serve\n\n# Generate via API\ncurl -X POST http://localhost:8000/api/generate \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\"spec_url\": \"https://petstore.swagger.io/v2/swagger.json\", \"enhance\": false}'\n\n# Response: {\"server_code\": \"...\", \"tools\": [...], \"api_name\": \"Petstore\"}\n```\n\n---\n\n## Configuration\n\nMCPForge works with zero configuration. Optionally create `mcpforge.yaml`:\n\n```yaml\nollama_url: \"http://localhost:11434\"\nenhance_model: \"qwen2.5:7b\"     # Model to use for description enhancement\nmax_tools: 50                    # Max tools per generated server\noutput_dir: \"./generated\"        # Default output directory\n```\n\n---\n\n## Architecture\n\n```\nmcpforge/\n├── mcpforge/           # Core library\n│   ├── parser.py       # OpenAPI 3.0 / Swagger 2.0 parser\n│   ├── generator.py    # MCP server code generator\n│   ├── enhancer.py     # Ollama description enhancer\n│   └── validator.py    # Generated code validator\n├── cli/main.py         # Typer CLI (mcpforge command)\n├── api/main.py         # FastAPI web API + UI\n├── examples/           # Built-in MCP server examples\n│   ├── github_mcp.py\n│   ├── weather_mcp.py\n│   └── calculator_mcp.py\n├── tests/              # pytest test suite\n└── docs/               # GitHub Pages website\n```\n\n---\n\n## Supported Features\n\n| Feature | Status |\n|---------|--------|\n| OpenAPI 3.0 | ✅ |\n| Swagger 2.0 | ✅ |\n| Bearer auth | ✅ |\n| API key auth | ✅ |\n| Path parameters | ✅ |\n| Query parameters | ✅ |\n| Request body | ✅ |\n| Ollama enhancement | ✅ optional |\n| Syntax validation | ✅ |\n| Web UI | ✅ |\n| Docker | ✅ |\n\n---\n\n## MCP Resources\n\n- [Model Context Protocol](https://modelcontextprotocol.io) — Official MCP site\n- [MCP Python SDK](https://github.com/modelcontextprotocol/python-sdk) — The SDK MCPForge uses\n- [MCP Servers](https://github.com/modelcontextprotocol/servers) — Community servers\n- [Claude Desktop MCP Guide](https://docs.anthropic.com/claude/docs/mcp) — Connect to Claude\n\n---\n\n## License\n\nMIT — see [LICENSE](LICENSE)\n\n---\n\nBuilt with Python, FastAPI, and the [MCP Python SDK](https://github.com/modelcontextprotocol/python-sdk).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Facunningham-ship-it%2Fmcpforge","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Facunningham-ship-it%2Fmcpforge","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Facunningham-ship-it%2Fmcpforge/lists"}