Skip to main content
Glama
enesjakozh
TykTechnologies

OpenAPI to MCP Server

by TykTechnologies
OverviewSchemaSourceRelated ServersDiscussionsAdmin
TypeScript
Hybrid

OpenAPI 到 MCP 服务器

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

概述

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

Related MCP server: Swagger MCP

特征

  • 从文件或 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 中设置

  1. 确保您的计算机上安装了Node.js

  2. 打开 Claude Desktop 并导航至“设置”>“开发者”

  3. 编辑配置文件（如果不存在则会创建）：

    • macOS： ~/Library/Application Support/Claude/claude_desktop_config.json

    • Windows： %APPDATA%\Claude\claude_desktop_config.json

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

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

  1. 重启Claude桌面

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

自定义配置

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

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

在光标中设置

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

    • 项目特定：项目目录中的.cursor/mcp.json

    • 全局：主目录中的~/.cursor/mcp.json

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

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

  1. 重新启动 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', '@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 路径的逗号分隔列表（支持诸如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 服务器将按以下顺序查找配置文件：

  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 <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 进行定制，并将其发布为软件包。

分叉和定制

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

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

  3. 配置默认设置：创建将与您的包捆绑在一起的自定义配置文件：

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

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

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

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

自定义 GitHub 工作流程

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

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

    name: Publish My Custom MCP Package

  2. 设置包范围（如果需要） ：如果要在 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"

  3. 设置 npm 令牌：在分叉存储库的设置中将您的 npm 令牌添加为名为NPM_TOKEN的 GitHub 机密。

发布您的定制包

自定义存储库后：

  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

  2. GitHub Actions 将：

    • 自动构建包

    • 更新 package.json 中的版本以匹配标签

    • 将捆绑的规范和配置发布到 npm

出版后的使用

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

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

# Run it
your-custom-mcp-server

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

执照

麻省理工学院

Available Tools

3 tools
createPetD
ParametersJSON Schema
NameRequiredDescriptionDefault
requestBodyYesParameter: requestBody

TDQS

D1/5.0
Behavior1/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Tool has no description.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness1/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Tool has no description.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness1/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Tool has no description.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters1/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Tool has no description.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose1/5

Does the description clearly state what the tool does and how it differs from similar tools?

Tool has no description.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines1/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Tool has no description.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

getPetByIdD
ParametersJSON Schema
NameRequiredDescriptionDefault
petIdYesEnhanced pet ID description from overlay

TDQS

D1/5.0
Behavior1/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Tool has no description.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness1/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Tool has no description.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness1/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Tool has no description.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters1/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Tool has no description.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose1/5

Does the description clearly state what the tool does and how it differs from similar tools?

Tool has no description.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines1/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Tool has no description.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

listPetsD
ParametersJSON Schema
NameRequiredDescriptionDefault
limitNoHow many items to return at one time

TDQS

D1/5.0
Behavior1/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Tool has no description.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness1/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Tool has no description.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness1/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Tool has no description.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters1/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Tool has no description.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose1/5

Does the description clearly state what the tool does and how it differs from similar tools?

Tool has no description.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines1/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Tool has no description.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

  1. 3 tool updatesv1.0.0
    • First observedcreatePet
    • First observedgetPetById
    • First observedlistPets
Deploy Server
One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

TDQS

D1.9/5.0

Scored across 3 tools

Disambiguation5/5

The three tools have clearly distinct purposes: createPet for creating a pet, getPetById for retrieving a specific pet by ID, and listPets for listing all pets. There is no overlap or ambiguity between these operations, making it easy for an agent to select the correct tool based on the desired action.

Naming Consistency5/5

All tool names follow a consistent verb_noun pattern: createPet, getPetById, and listPets. The naming is uniform, with no mixing of conventions (e.g., snake_case or camelCase variations), making the set predictable and readable.

Tool Count3/5

With only 3 tools, the server feels thin for a general OpenAPI-to-MCP conversion purpose, which might imply broader functionality. However, for a specific pet-related API subset, this count is minimal but covers basic CRUD operations (create, read, list), though it lacks update and delete tools.

Completeness3/5

The tool set covers create, get by ID, and list operations, providing a basic CRUD foundation for pets. However, it lacks update and delete tools, which are common in such domains, and there are no tools for other potential resources or advanced operations, indicating notable gaps in coverage.

Maintenance

ActivityInactive
ResponsivenessNo issues

Resources

Related MCP Connectors

Related MCP Servers

Appeared in Searches