OpenAPI 到 MCP 服务器

这款工具可根据 OpenAPI/Swagger 规范创建 MCP（模型上下文协议）服务器，使 AI 助手能够与您的 API 进行交互。您可以为特定的 API 或服务创建您自己的品牌化定制 MCP 。

概述

该项目创建了一个动态的 MCP 服务器，将 OpenAPI 规范转换为 MCP 工具。它通过模型上下文协议 (MCP) 将 REST API 与 AI 助手无缝集成，将任何 API 转换为 AI 可访问的工具。

特征

从文件或 HTTP/HTTPS URL 动态加载 OpenAPI 规范
支持从文件或 HTTP/HTTPS URL 加载的OpenAPI 覆盖
OpenAPI 操作到 MCP 工具的可定制映射
使用针对 operationId 和 URL 路径的 glob 模式对操作进行高级过滤
通过格式保存和位置元数据进行全面的参数处理
API 身份验证处理
用于配置 MCP 服务器的 OpenAPI 元数据（标题、版本、描述）
分层描述回退（操作描述→操作摘要→路径摘要）
通过环境变量和 CLI 支持自定义 HTTP 标头
用于 API 请求跟踪和识别的 X-MCP 标头
支持路径级别的自定义x-mcp扩展以覆盖工具名称和描述

与人工智能助手一起使用

此工具会创建一个 MCP 服务器，允许 AI 助手与 OpenAPI 规范定义的 API 进行交互。主要使用方式是配置您的 AI 助手，使其直接作为 MCP 工具运行。

在 Claude Desktop 中设置

确保您的计算机上已安装Node.js
打开 Claude Desktop 并导航至“设置”>“开发者”
编辑配置文件（如果不存在则会创建）：
- macOS： ~/Library/Application Support/Claude/claude_desktop_config.json
- Windows： %APPDATA%\Claude\claude_desktop_config.json
添加此配置（根据需要自定义）：

{
  "mcpServers": {
    "api-tools": {
      "command": "npx",
      "args": [
        "-y",
        "@tyktechnologies/api-to-mcp",
        "--spec",
        "https://petstore3.swagger.io/api/v3/openapi.json"
      ],
      "enabled": true
    }
  }
}

重启Claude桌面
您现在应该会在聊天输入框中看到一个锤子图标。点击它即可访问您的 API 工具。

自定义配置

您可以使用各种选项调整args数组来定制您的 MCP 服务器：

{
  "mcpServers": {
    "my-api": {
      "command": "npx",
      "args": [
        "-y",
        "@tyktechnologies/api-to-mcp",
        "--spec",
        "./path/to/your/openapi.json",
        "--overlays",
        "./path/to/overlay.json,https://example.com/api/overlay.json",
        "--whitelist",
        "getPet*,POST:/users/*",
        "--targetUrl",
        "https://api.example.com"
      ],
      "enabled": true
    }
  }
}

在光标中设置

在以下位置之一创建配置文件：
- 项目特定：项目目录中的.cursor/mcp.json
- 全局：主目录中的~/.cursor/mcp.json
添加此配置（根据您的 API 需要进行调整）：

{
  "servers": [
    {
      "command": "npx",
      "args": [
        "-y",
        "@tyktechnologies/api-to-mcp",
        "--spec",
        "./path/to/your/openapi.json"
      ],
      "name": "My API Tools"
    }
  ]
}

重新启动 Cursor 或重新加载窗口

与 Vercel AI SDK 一起使用

您还可以使用 Vercel AI SDK 的 MCP 客户端直接在 JavaScript/TypeScript 应用程序中使用此 MCP 服务器：

import { experimental_createMCPClient } from 'ai';
import { Experimental_StdioMCPTransport } from 'ai/mcp-stdio';
import { generateText } from 'ai';
import { createGoogleGenerativeAI } from '@ai-sdk/google';

// Initialize the Google Generative AI provider
const google = createGoogleGenerativeAI({
  apiKey: process.env.GOOGLE_API_KEY, // Set your API key in environment variables
});
const model = google('gemini-2.0-flash');

// Create an MCP client with stdio transport
const mcpClient = await experimental_createMCPClient({
  transport: {
    type: 'stdio',
    command: 'npx', // Command to run the MCP server
    args: ['-y', '@tyktechnologies/api-to-mcp', '--spec', 'https://petstore3.swagger.io/api/v3/openapi.json'], // OpenAPI spec
    env: {
      // You can set environment variables here
      // API_KEY: process.env.YOUR_API_KEY,
    },
  },
});

async function main() {
  try {
    // Retrieve tools from the MCP server
    const tools = await mcpClient.tools();

    // Generate text using the AI SDK with MCP tools
    const { text } = await generateText({
      model,
      prompt: 'List all available pets in the pet store using the API.',
      tools, // Pass the MCP tools to the model
    });

    console.log('Generated text:', text);
  } catch (error) {
    console.error('Error:', error);
  } finally {
    // Always close the MCP client to release resources
    await mcpClient.close();
  }
}

main();

配置

配置通过环境变量、命令行选项或 JSON 配置文件进行管理：

命令行选项

# Start with specific OpenAPI spec file
@tyktechnologies/api-to-mcp --spec=./path/to/openapi.json

# Apply overlays to the spec
@tyktechnologies/api-to-mcp --spec=./path/to/openapi.json --overlays=./path/to/overlay.json,https://example.com/api/overlay.json

# Include only specific operations (supports glob patterns)
@tyktechnologies/api-to-mcp --spec=./path/to/openapi.json --whitelist="getPet*,POST:/users/*"

# Specify target API URL
@tyktechnologies/api-to-mcp --spec=./path/to/openapi.json --targetUrl=https://api.example.com

# Add custom headers to all API requests
@tyktechnologies/api-to-mcp --spec=./path/to/openapi.json --headers='{"X-Api-Version":"1.0.0"}'

# Disable the X-MCP header
@tyktechnologies/api-to-mcp --spec=./path/to/openapi.json --disableXMcp

环境变量

您可以在.env文件中或直接在您的环境中设置这些：

OPENAPI_SPEC_PATH ：OpenAPI 规范文件的路径
OPENAPI_OVERLAY_PATHS ：以逗号分隔的覆盖 JSON 文件的路径
TARGET_API_BASE_URL ：API 调用的基本 URL（覆盖 OpenAPI 服务器）
MCP_WHITELIST_OPERATIONS ：要包含的操作 ID 或 URL 路径的逗号分隔列表（支持诸如getPet*或GET:/pets/*之类的 glob 模式）
MCP_BLACKLIST_OPERATIONS ：要排除的操作 ID 或 URL 路径的逗号分隔列表（支持 glob 模式，如果使用白名单则忽略）
API_KEY ：目标 API 的 API 密钥（如果需要）
SECURITY_SCHEME_NAME ：需要 API 密钥的安全方案的名称
SECURITY_CREDENTIALS ：包含多个方案的安全凭证的 JSON 字符串
CUSTOM_HEADERS ：包含自定义标头的 JSON 字符串，包含在所有 API 请求中
HEADER_* ：任何以HEADER_开头的环境变量都将作为自定义标头添加（例如， HEADER_X_API_Version=1.0.0添加标头X-API-Version: 1.0.0 ）
DISABLE_X_MCP ：设置为true以禁用向所有 API 请求添加X-MCP: 1标头
CONFIG_FILE ：JSON 配置文件的路径

JSON 配置

您也可以使用 JSON 配置文件来代替环境变量或命令行选项。MCP 服务器将按以下顺序查找配置文件：

--config命令行选项指定的路径
CONFIG_FILE环境变量指定的路径
当前目录中的config.json
当前目录中的openapi-mcp.json
当前目录中的.openapi-mcp.json

JSON 配置文件示例：

{
  "spec": "./path/to/openapi-spec.json",
  "overlays": "./path/to/overlay1.json,https://example.com/api/overlay.json",
  "targetUrl": "https://api.example.com",
  "whitelist": "getPets,createPet,/pets/*",
  "blacklist": "deletePet,/admin/*",
  "apiKey": "your-api-key",
  "securitySchemeName": "ApiKeyAuth",
  "securityCredentials": {
    "ApiKeyAuth": "your-api-key",
    "OAuth2": "your-oauth-token"
  },
  "headers": {
    "X-Custom-Header": "custom-value",
    "User-Agent": "OpenAPI-MCP-Client/1.0"
  },
  "disableXMcp": false
}

根目录中的config.example.json提供了带有解释性注释的完整示例配置文件。

配置优先级

配置设置按以下优先顺序应用（从高到低）：

命令行选项
环境变量
JSON配置文件

发展

安装

# Clone the repository
git clone <repository-url>
cd openapi-to-mcp-generator

# Install dependencies
npm install

# Build the project
npm run build

本地测试

# Start the MCP server
npm start

# Development mode with auto-reload
npm run dev

定制并发布您自己的版本

您可以使用此仓库作为基础，创建您自己的定制 OpenAPI 到 MCP 服务器。本节介绍如何 fork 此仓库，根据您的特定 API 进行定制，并将其发布为软件包。

分叉和定制

分叉存储库：在 GitHub 上分叉此存储库以创建您可以自定义的自己的副本。
添加您的 OpenAPI 规范：
# Create a specs directory if it doesn't exist mkdir -p specs # Add your OpenAPI specifications cp path/to/your/openapi-spec.json specs/ # Add any overlay files cp path/to/your/overlay.json specs/
配置默认设置：创建将与您的包捆绑在一起的自定义配置文件：
# Copy the example config cp config.example.json config.json # Edit the config to point to your bundled specs # and set any default settings
更新 package.json ：
{ "name": "your-custom-mcp-server", "version": "1.0.0", "description": "Your customized MCP server for specific APIs", "files": [ "dist/**/*", "config.json", "specs/**/*", "README.md" ] }
确保规格已捆绑：package.json 中的files字段（如上所示）确保您的规格和配置文件将包含在已发布的包中。

自定义 GitHub 工作流程

该仓库包含一个 GitHub Actions 工作流程，用于自动发布到 npm。要为你的 fork 仓库自定义它：

更新工作流名称：如果需要，编辑.github/workflows/publish-npm.yaml以更新名称：
name: Publish My Custom MCP Package
设置包范围（如果需要） ：如果您想在 npm 组织范围内发布，请取消注释并修改工作流文件中的范围行：
- name: Setup Node.js uses: actions/setup-node@v4 with: node-version: "18" registry-url: "https://registry.npmjs.org/" # Uncomment and update with your organization scope: scope: "@your-org"
设置 npm 令牌：在分叉存储库的设置中将您的 npm 令牌添加为名为NPM_TOKEN的 GitHub 机密。

发布您的定制包

自定义存储库后：

创建并推送标签：
# Update version in package.json (optional, the workflow will update it based on the tag) npm version 1.0.0 # Push the tag git push --tags
GitHub Actions 将：
- 自动构建包
- 更新 package.json 中的版本以匹配标签
- 将捆绑的规范和配置发布到 npm

出版后的使用

您的自定义包的用户可以通过 npm 安装和使用它：

# Install your customized package
npm install your-custom-mcp-server -g

# Run it
your-custom-mcp-server

它们可以通过环境变量或命令行选项覆盖您的默认设置，如配置部分所述。

执照

麻省理工学院

OpenAPI to MCP Server

Integrations