使用说明

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中设置

确保你有 Node.js 已安装在您的计算机上
打开克劳德桌面，导航到“设置”>“开发人员”
编辑配置文件（如果不存在，将创建配置文件）：
- macOS： ~/Library/Application Support/Claude/claude_desktop_config.json
- 窗户： %APPDATA%\Claude\claude_desktop_config.json
添加此配置（根据需要进行自定义）：

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

重新启动克劳德桌面
现在，您应该在聊天输入框中看到一个锤子图标。单击它访问您的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
    }
  }
}

在游标中设置

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

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

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

使用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服务器将按以下顺序查找配置文件：

指定的路径 --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服务器的基础。本节解释了如何分叉存储库，为您的特定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"
  ]
}

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

自定义GitHub工作流

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

更新工作流名称: 编辑 .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令牌添加为名为的GitHub secret NPM_TOKEN 在分叉存储库的设置中。

发布您的定制套餐

自定义存储库后：

创建并推送标签:

# 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操作将:
- 自动构建包
- 更新package.json中的版本以匹配标签
- 使用捆绑的规范和配置发布到npm

发布后使用

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

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

# Run it
your-custom-mcp-server

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

许可证

麻省理工学院