使用说明

FastMCP OpenAPI

一个FastMCP封装器，能够根据OpenAPI规范动态生成MCP（模型上下文协议）工具。

快速入门

先决条件

Python 3.8+ 及 pip
Node.js 16+（用于 MCP Inspector）
OpenAI API密钥（用于LangChain演示）

安装

pip install fastmcp-openapi

基本用法

# Generate MCP tools from any OpenAPI spec
fastmcp-openapi --spec https://petstore.swagger.io/v2/swagger.json

# With authentication
fastmcp-openapi --spec https://api.example.com/openapi.json --auth-header "Bearer your-token"

# Multiple APIs
fastmcp-openapi --spec api1.json --spec api2.json --spec api3.json

使用MCP Inspector进行测试

# Install MCP Inspector
npm install -g @modelcontextprotocol/inspector

# Test your OpenAPI tools
npx @modelcontextprotocol/inspector fastmcp-openapi --spec examples/simple_api.json

# Test Petstore API with Inspector
npx @modelcontextprotocol/inspector fastmcp-openapi --spec https://petstore.swagger.io/v2/swagger.json --base-url https://petstore.swagger.io/v2

Claude 桌面集成

在您的Claude桌面配置中添加：

{
  "mcpServers": {
    "openapi-server": {
      "command": "fastmcp-openapi",
      "args": ["--spec", "https://api.example.com/openapi.json", "--auth-header", "Bearer your-token"]
    }
  }
}

特点/特性

✅ 动态工具生成自动将OpenAPI操作转换为MCP工具
✅ 类型安全使用OpenAPI模式进行完整参数验证
✅ 认证承载令牌、API密钥、基本认证
✅ **多个应用程序编程接口（APIs）**在一个服务器中加载多个OpenAPI规范
✅ 实时添加/删除API而无需重启

命令行选项

fastmcp-openapi --help

Options:
  --spec TEXT          OpenAPI specification URL or file path (can be used multiple times)
  --name TEXT          Server name (default: "OpenAPI Server")
  --auth-header TEXT   Authorization header (e.g., 'Bearer token123'). Must match order of --spec options.
  --base-url TEXT      Override base URL for API calls. Must match order of --spec options.
  --config TEXT        JSON config file with API specifications
  --transport TEXT     Transport: stdio, streamable-http, sse (default: stdio)
  --port INTEGER       Port for HTTP/SSE transport (default: 8000)
  --debug             Enable debug logging

程序化使用

from fastmcp_openapi import OpenAPIServer

# Create server
server = OpenAPIServer("My API Server")

# Add OpenAPI specs
await server.add_openapi_spec(
    name="petstore",
    spec_url="https://petstore.swagger.io/v2/swagger.json",
    auth_header="Bearer your-token"
)

# Run server
server.run()

示例

多个具有不同认证方式的API

# Multiple APIs with different base URLs and auth
fastmcp-openapi \
  --spec https://petstore.swagger.io/v2/swagger.json \
  --spec https://api.github.com/openapi.yaml \
  --spec ./local-api.json \
  --base-url https://petstore.swagger.io/v2 \
  --base-url https://api.github.com \
  --base-url http://localhost:3000 \
  --auth-header "Bearer petstore-token" \
  --auth-header "Bearer github-token" \
  --auth-header "Basic local-auth"

# Each API gets its own tools with prefixes:
# - api_1_getPetById (Petstore)
# - api_2_getUser (GitHub)  
# - api_3_createItem (Local API)

混合API源

# Combine remote and local APIs
fastmcp-openapi \
  --spec https://petstore.swagger.io/v2/swagger.json \
  --spec examples/simple_api.json \
  --spec https://jsonplaceholder.typicode.com/openapi.json \
  --base-url https://petstore.swagger.io/v2 \
  --base-url http://localhost:8080 \
  --base-url https://jsonplaceholder.typicode.com

# Creates unified MCP server with tools from all APIs

认证API

fastmcp-openapi \
  --spec https://api.example.com/openapi.json \
  --auth-header "Bearer your-oauth-token" \
  --base-url "https://api.example.com/v1"

开发模式

# HTTP mode for web testing
fastmcp-openapi \
  --spec examples/simple_api.json \
  --transport streamable-http \
  --port 8080 \
  --debug

# SSE mode for MCP Inspector
fastmcp-openapi \
  --spec https://petstore.swagger.io/v2/swagger.json \
  --base-url https://petstore.swagger.io/v2 \
  --transport sse \
  --port 8081 \
  --debug

LangChain 集成

# Install required dependencies
pip install langchain-openai langchain-mcp-adapters langgraph

# Set OpenAI API key
export OPENAI_API_KEY="your-openai-api-key"

# Start FastMCP server with HTTP transport
fastmcp-openapi \
  --spec https://petstore.swagger.io/v2/swagger.json \
  --base-url https://petstore.swagger.io/v2 \
  --transport streamable-http \
  --port 8081

# Run LangChain test (in another terminal)
python test_mcp_langchain.py

LangChain的集成使得AI代理能够使用生成的MCP工具与API进行自然语言交互。

它是如何工作的

加载OpenAPI规范获取并解析OpenAPI/Swagger规范
生成工具为每个API操作创建带有适当模式的MCP工具
处理请求验证参数并进行身份验证的HTTP请求
返回结果为AI处理格式化API响应

支持的功能

✅ OpenAPI 3.0.x，3.1.x，Swagger 2.0
✅ 路径/查询参数、头部信息、请求体
认证（承载者、API密钥、基本）
✅ 参数验证和类型检查
✅ 一个服务器上部署多个API
✅ 多种传输方式：stdio、streamable-http、sse
✅ 与LangChain集成的AI代理
✅ MCP Inspector 支持交互式测试

测试与示例

使用Petstore API进行快速测试

# 1. Start server with SSE transport
fastmcp-openapi --spec https://petstore.swagger.io/v2/swagger.json --base-url https://petstore.swagger.io/v2 --transport sse --port 8081

# 2. Test with MCP Inspector (in another terminal)
npx @modelcontextprotocol/inspector fastmcp-openapi --spec https://petstore.swagger.io/v2/swagger.json --base-url https://petstore.swagger.io/v2

# 3. Test with LangChain (requires OPENAI_API_KEY)
python test_mcp_langchain.py

可用的交通方式

**stdio**标准输入/输出（默认设置，适用于Claude桌面版）
**streamable-http**基于HTTP的传输（用于LangChain集成）
**sse**服务器发送事件传输（用于MCP Inspector）

多个API管理

FastMCP OpenAPI 支持将多个 OpenAPI 规范合并到一个 MCP 服务器中，每个规范都有其自己的基础 URL 和认证方式。

配置方法

方法1：JSON配置（推荐）

创建一个JSON配置文件来清晰地定义每个API：

{
  "apis": [
    {
      "name": "petstore",
      "spec": "https://petstore.swagger.io/v2/swagger.json",
      "base_url": "https://petstore.swagger.io/v2",
      "auth": "Bearer petstore-api-key"
    },
    {
      "name": "simple_api", 
      "spec": "examples/simple_api.json",
      "base_url": "http://localhost:8080"
    }
  ]
}

# Use the config file
fastmcp-openapi --config examples/multi_api_config.json --transport sse --port 8081

方法2：命令行参数（位置匹配）

⚠️ 重要的参数必须按相同顺序排列——每个 --base-url 和 --auth-header 与相应的（内容/情况）相匹配 --spec 按位置。

# Order matters: spec[0]→base_url[0]→auth[0], spec[1]→base_url[1]→auth[1], etc.
fastmcp-openapi \
  --spec https://petstore.swagger.io/v2/swagger.json \     # Position 0
  --spec examples/simple_api.json \                       # Position 1  
  --spec https://api.github.com/openapi.yaml \            # Position 2
  --base-url https://petstore.swagger.io/v2 \             # Position 0 → spec[0]
  --base-url http://localhost:8080 \                      # Position 1 → spec[1]
  --base-url https://api.github.com \                     # Position 2 → spec[2]
  --auth-header "Bearer petstore-key" \                   # Position 0 → spec[0]
  --auth-header "" \                                      # Position 1 → spec[1] (no auth)
  --auth-header "Bearer github-key"                       # Position 2 → spec[2]

好处；福利

统一界面通过一个MCP服务器访问多个API
个性化配置每个API都可以有自己的基础URL和认证方式
工具命名空间工具会自动添加前缀以避免冲突
混合来源结合远程API、本地服务和文件

工具命名规范

当加载多个API时，工具会自动添加前缀：

单一API: operationId → getPetById
多个API: api_name_operationId → petstore_getPetById， github_getUser

发展

git clone <repository>
cd fastmcp-openapi
pip install -e ".[dev]"
pytest

许可证

麻省理工学院许可证（MIT License）