MCP Openapi Oauth2

MCP OpenAPI OAuth2 服务器

根据OpenAPI规范自动生成MCP工具的服务器。

设置

本地开发

pnpm install
pnpm run generate  # OpenAPI からツール生成
pnpm run dev       # サーバー起動 (http://localhost:3030)

Docker

在构建Docker镜像时 specs/ 复制目录的OpenAPI规范以生成工具。

1. 准备OpenAPI规范：

specs/ 在目录中放置以下内容：

• specs-config.json - 工具生成设置
• OpenAPI YAML/JSON 文件

specs/specs-config.json 示例：

[
  {
    "name": "myapi",
    "spec": "./specs/my-api.yaml",
    "baseUrl": "https://api.example.com"
  }
]

2. 构建：

docker build -t mcp-openapi-oauth2 .

若使用不同的OpenAPI规范specs/ 请对其进行编辑并重新构建。

3. 启动：

# 基本起動
docker run -d -p 3030:3030 \
  -e API_BASE_URL=https://api.example.com \
  mcp-openapi-oauth2

# OAuth2認証付き
docker run -d -p 3030:3030 \
  -e API_BASE_URL=https://api.example.com \
  -e OAUTH_CLIENT_ID=your-client-id \
  -e OAUTH_CLIENT_SECRET=your-client-secret \
  -e OAUTH_TOKEN_URL=https://auth.example.com/oauth/token \
  -e OAUTH_SCOPES="read write" \
  mcp-openapi-oauth2

4. 健康检查：

curl http://localhost:3030/health

命令

开发

• pnpm run generate - 从OpenAPI生成工具

- specs/specs-config.json 从加载设置

• pnpm run dev - 启动开发服务器（端口3030）
• pnpm run build - 构建
• pnpm run lint - 林特
• pnpm run format - 格式

调试工具

• pnpm run debug:mock-api - 启动模拟API服务器（端口8080）
• pnpm run debug:list-tools - 显示工具列表
• pnpm run debug:call-tool - 工具执行（例如： pnpm run debug:call-tool getPetById '{"petId": "1"}'）
• pnpm run debug:inspector - 启动MCP Inspector（在浏览器中测试）

终端设备

• GET /health - 健康检查
• GET/POST /mcp - MCP 可流式传输HTTP终端（用于Claude Desktop）

与Mock API的集成

工具是环境变量API_BASE_URL然后从指定的API服务器获取数据。

# Mock APIサーバー起動 (port 8080)
pnpm run debug:mock-api

# MCPサーバー起動 (デフォルトでlocalhost:8080に接続)
pnpm run dev

# または別のAPIサーバーを指定
API_BASE_URL=https://api.example.com pnpm run dev

架构

specs/                     # OpenAPI仕様ファイル（Dockerボリュームマウント対象）
├── specs-config.json      # ツール生成設定
├── petstore.yaml          # サンプル: Petstore API
└── todo.yaml              # サンプル: Todo API

src/
├── index.ts               # サーバー (Hono + StreamableHTTP)
├── api-executor.ts        # OAuth2トークン注入ラッパー
├── auth/
│   └── oauth2-client.ts   # OAuth2 Client Credentials Flow
├── generator/             # OpenAPI → ツール生成
│   └── generate-from-openapi.ts
└── __generated__/         # 自動生成されたファイル
    ├── petstore/          # Petstore API tools
    ├── todo/              # Todo API tools
    ├── common/            # 共通コード (executor, security)
    └── index.ts           # aggregator

debug/
├── mock-api-server.ts    # Mock APIサーバー
├── list-tools.ts         # ツール一覧表示
└── call-tool.ts          # ツール実行

OAuth2认证

支持OAuth2客户端凭证流程。设置环境变量后，所有请求将 Authorization: Bearer ${token} 会自动授予。

export OAUTH_CLIENT_ID="your-client-id"
export OAUTH_CLIENT_SECRET="your-client-secret"
export OAUTH_TOKEN_URL="https://auth.example.com/oauth/token"
export OAUTH_SCOPES="read write"  # オプション

pnpm run dev

• 令牌自动获取、缓存、更新
• 在多个OpenAPI规范中共享同一令牌
• 如未设置环境变量，则无需认证即可运行

环境变量

服务器设置

• PORT - MCP服务器端口（默认：3030）
• API_BASE_URL - 要连接的API的基础URL（默认：http://localhost:8080）

OAuth2 认证（可选）

• OAUTH_CLIENT_ID - OAuth2 客户端 ID
• OAUTH_CLIENT_SECRET - OAuth2 客户端密钥
• OAUTH_TOKEN_URL - OAuth2令牌端点URL
• OAUTH_SCOPES - OAuth2 权限范围（空格分隔，可选）

用于调试

• MOCK_API_PORT - 模拟API服务器的端口（默认：8080）
• OPENAPI_SPEC - 用于模拟API的OpenAPI规范路径（默认：./petstore.yaml）

来自MCP客户端的验证方法

在能够通过http://localhost:3030/mcp连接到服务器的前提下，可以执行以下操作

MCP检查员

pnpm run debug:inspector 通过inspector进行验证

克劳德·科德

如果使用claude code进行连接，可以通过以下命令进行确认

$ claude mcp add --transport http example http://localhost:3030/mcp
$ claude
claude> /mcp