内容
<div align="center">
# mcpgen
**30秒将任何API转换为MCP服务器**
[](https://pypi.org/project/mcpgen-cli/)
[](https://www.python.org)
[](https://opensource.org/licenses/MIT)
[](https://modelcontextprotocol.io)
[](https://github.com/JnanaSrota/mcpgen/stargazers)
[](https://github.com/JnanaSrota/mcpgen/actions)
</div>
---
<div align="center">
<img src="./demo.gif" alt="mcpgen demo" width="700">
</div>
指向 `mcpgen` 一个OpenAPI规范或Postman集合。获取一个您拥有的完整的Python MCP服务器——无需在运行时依赖mcpgen，无需代理，无需锁定。阅读它。修改它。部署它。
---
## 安装
```bash
pip install mcpgen-cli
```
## 快速开始
```bash
# 从URL
mcpgen https://petstore3.swagger.io/api/v3/openapi.json
# 从本地OpenAPI文件（JSON或YAML）
mcpgen stripe.yaml
# 从Postman集合
mcpgen postman_collection.json
# 预览而不写入任何内容
mcpgen openapi.json --dry-run
# 自定义输出目录和服务器名称
mcpgen openapi.json --output ~/my-mcp-servers --name "My API"
```
就这样。`mcpgen` 读取您的规范并将Python MCP服务器写入磁盘。
---
## 您获得的内容
一个包含您拥有的源代码的自包含目录：
```
stripe_api_mcp/
├── server.py ← MCP服务器（读取它，编辑它，它是您的）
└── requirements.txt ← httpx，mcp
```
**立即运行：**
```bash
cd stripe_api_mcp
pip install -r requirements.txt
export STRIPE_API_TOKEN="sk_live_..."
python server.py
```
**生成的 `server.py` 示例如下：**
```python
#!/usr/bin/env python3
"""
Stripe API MCP Server
由mcpgen生成 — https://github.com/JnanaSrota/mcpgen
此文件是您的。可以自由修改。
"""
import os, asyncio, httpx
from mcp.server import Server
from mcp.server.stdio import stdio_server
from mcp import types
BASE_URL = "https://api.stripe.com"
AUTH_TOKEN = os.environ.get("STRIPE_API_TOKEN", "")
app = Server("stripe-api")
@app.call_tool()
async def _handle_get_customers(name: str, arguments: dict):
if name != "get_customers":
raise ValueError(f"Unknown tool: {name}")
url = BASE_URL + "/v1/customers"
query_params = {}
if "limit" in arguments:
query_params["limit"] = arguments["limit"]
async with httpx.AsyncClient(timeout=30.0) as client:
response = await client.get(url, params=query_params,
headers={"Authorization": f"Bearer {AUTH_TOKEN}"})
response.raise_for_status()
return [types.TextContent(type="text", text=response.text)]
# ... 每个API端点一个函数
@app.list_tools()
async def list_tools(): ...
if __name__ == "__main__":
asyncio.run(stdio_server(app))
```
无黑盒。运行时无依赖。只是Python。
---
## 添加到Claude Desktop
`mcpgen` 打印确切的配置片段以粘贴到您的 `claude_desktop_config.json` 中：
```json
{
"mcpServers": {
"stripe-api-mcp": {
"command": "python",
"args": ["/path/to/stripe_api_mcp/server.py"],
"env": { "STRIPE_API_TOKEN": "your-key-here" }
}
}
}
```
**配置文件位置：**
- macOS: `~/Library/Application Support/Claude/claude_desktop_config.json`
- Windows: `%APPDATA%\Claude\claude_desktop_config.json`
---
## 为什么选择源代码而不是代理？
大多数API-to-MCP工具都是**运行时代理** —— 它们位于Claude和您的API之间，并且您依赖它们继续运行。
`mcpgen` 生成**您拥有的源代码**。输出是一个普通的Python文件。您可以：
- 读取发生的每一行
- 修改身份验证逻辑，添加重试，调整错误处理
- 在没有任何依赖mcpgen的情况下将其部署到任何地方
- 将其提交到您自己的仓库，版本控制，在PR中审查
`mcpgen` 是一个构建工具。在生成时需要。运行时从不需要。
---
## 支持的输入
| 格式 | 示例 |
|---|---|
| OpenAPI 3.x JSON | `mcpgen openapi.json` |
| OpenAPI 3.x YAML | `mcpgen api.yaml` |
| 指向OpenAPI规范的URL | `mcpgen https://api.example.com/openapi.json` |
| Postman Collection v2.1 | `mcpgen collection.json` |
**已测试：**
- [Petstore](https://petstore3.swagger.io/api/v3/openapi.json) — 19个端点 → 19个工具
- GitHub REST API（子集）
- Stripe API（子集）
- 任何有效的OpenAPI 3.x规范
---
## 身份验证支持
`mcpgen` 从规范中自动检测API的身份验证方案：
| 方案 | OpenAPI声明 | 生成的环境变量 |
|---|---|---|
| Bearer令牌 | `type: http, scheme: bearer` | `YOUR_API_TOKEN` |
| API密钥 | `type: apiKey` | `YOUR_API_API_KEY` |
| 基本身份验证 | `type: http, scheme: basic` | `YOUR_API_CREDENTIALS` |
| 无 | 无`securitySchemes` | — |
OAuth2流程近似为Bearer令牌 — 您手动提供令牌。
---
## CLI参考
```
用法：mcpgen [选项] 输入
30秒将任何API转换为MCP服务器。
参数：
输入 OpenAPI JSON/YAML文件，Postman集合或URL [必填]
选项：
-o, --output PATH 输出目录（默认：当前目录）
-n, --name TEXT 覆盖生成的服务器名称
--dry-run 打印生成的代码而不写入文件
--no-color 禁用彩色输出
-v, --version 显示版本并退出
--help 显示此消息并退出
```
---
## 路线图
- [ ] TypeScript输出 (`--lang ts`) 使用 `@modelcontextprotocol/sdk`
- [ ] Swagger 2.x支持（自动检测，单独解析器）
- [ ] 从基准域名自动检测OpenAPI URL (`/.well-known/openapi.json`, `/api-docs`, 等)
- [ ] `--update-claude-config` 标志以自动修补 `claude_desktop_config.json`
- [ ] 深度嵌套模式的递归 `$ref` 解析
欢迎PR。参见 [CONTRIBUTING.md](./CONTRIBUTING.md).
---
## 贡献
```bash
git clone https://github.com/JnanaSrota/mcpgen
cd mcpgen
pip install -e ".[dev]"
pytest tests/ -v
```
代码库有三个干净的层：
```
输入（文件/URL）
↓
loader.py ← 检测格式，路由到正确的解析器
↓
openapi.py / postman.py ← 解析为MCPSpec（内部IR）
↓
generator/python.py ← 渲染Jinja2模板 → server.py
```
添加新的输入格式：编写一个返回`MCPSpec`的解析器。其他内容不变。
添加新的输出语言：编写一个使用`MCPSpec`的生成器。其他内容不变。
---
## 许可证
MIT — 生成的代码您可以任意使用。
