OpenAPI to MCP Server

OpenAPI到MCP服务器

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

概述

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

特性

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

使用AI助手

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

在Claude Desktop中设置

1. 确保你有 已安装在您的计算机上

1. 打开克劳德桌面，导航到“设置”>“开发人员”

1. 编辑配置文件（如果不存在，将创建配置文件）：

- macOS： ~/Library/Application Support/Claude/claude_desktop_config.json - 窗户： %APPDATA%\Claude\claude_desktop_config.json

1. 添加此配置（根据需要进行自定义）：

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

1. 重新启动克劳德桌面
2. 现在，您应该在聊天输入框中看到一个锤子图标。单击它访问您的API工具。

自定义配置

您可以调整 args 阵列，使用各种选项自定义您的MCP服务器：

{
  "mcpServers": {
    "my-api": {
      "command": "npx",
      "args": [
        "-y",
        "@tyk-technologies/api-to-mcp@latest",
        "--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
    }
  }
}

在游标中设置

1. 在以下位置之一创建配置文件：

- 项目具体： .cursor/mcp.json 在您的项目目录中 - 全球的： ~/.cursor/mcp.json 在您的主目录中

1. 添加此配置（根据API的需要进行调整）：

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

1. 重新启动光标或重新加载窗口

使用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', '@tyk-technologies/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
@tyk-technologies/api-to-mcp --spec=./path/to/openapi.json

# Apply overlays to the spec
@tyk-technologies/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)
@tyk-technologies/api-to-mcp --spec=./path/to/openapi.json --whitelist="getPet*,POST:/users/*"

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

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

# Disable the X-MCP header
@tyk-technologies/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路径列表（支持glob模式，如 getPet* 或 GET:/pets/*)
• MCP_BLACKLIST_OPERATIONS：逗号分隔的操作ID或要排除的URL路径列表（支持glob模式，如果使用白名单则忽略）
• API_KEY：目标API的API密钥（如果需要）
• SECURITY_SCHEME_NAME：需要API密钥的安全方案的名称
• SECURITY_CREDENTIALS：包含多个方案的安全凭据的JSON字符串
• CUSTOM_HEADERS：包含要包含在所有API请求中的自定义标头的JSON字符串
• HEADER_*：以开头的任何环境变量 HEADER_ 将被添加为自定义标头（例如。， HEADER_X_API_Version=1.0.0 添加标题 X-API-Version: 1.0.0)
• DISABLE_X_MCP：设置为 true 要禁用添加 X-MCP: 1 所有API请求的头
• CONFIG_FILE：JSON配置文件的路径

JSON配置

您还可以使用JSON配置文件，而不是环境变量或命令行选项。MCP服务器将按以下顺序查找配置文件：

1. 指定的路径 --config 命令行选项
2. 指定的路径 CONFIG_FILE 环境变量
3. config.json 在当前目录中
4. openapi-mcp.json 在当前目录中
5. .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 在根目录中。

配置优先级

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

1. 命令行选项
2. 环境变量
3. JSON配置文件

发展

安装

# Clone the repository
git clone 
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服务器的基础。本节解释了如何分叉存储库，为您的特定API进行自定义，并将其作为包发布。

分叉和定制

1. 分叉存储库:

在GitHub上分叉此存储库，以创建您可以自定义的副本。

1. 添加您的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/

1. 配置默认设置:

创建一个将与您的软件包捆绑在一起的自定义配置文件：

   # Copy the example config
   cp config.example.json config.json

   # Edit the config to point to your bundled specs
   # and set any default settings

1. 更新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"
     ]
   }

1. 确保规格捆绑在一起:

这 files package.json中的字段（如上所示）确保您的规范和配置文件将包含在已发布的包中。

自定义GitHub工作流

该仓库包含一个GitHub Actions工作流，用于自动发布到npm。要为您的分叉仓库进行自定义：

1. 更新工作流名称:

编辑 .github/workflows/publish-npm.yaml 如果需要，更新名称：

   name: Publish My Custom MCP Package

1. 设置包范围（如果需要）:

如果你想在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"

1. 设置npm令牌:

将你的npm令牌添加为名为的GitHub secret NPM_TOKEN 在分叉存储库的设置中。

发布您的定制套餐

自定义存储库后：

1. 创建并推送标签:

   # 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

1. GitHub操作将:

- 自动构建包 - 更新package.json中的版本以匹配标签 - 使用捆绑的规范和配置发布到npm

发布后使用

自定义包的用户可以安装并使用npm：

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

# Run it
your-custom-mcp-server

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

许可证

麻省理工学院