OpenAPI에서 MCP 서버로

OpenAPI/Swagger 사양을 기반으로 MCP(모델 컨텍스트 프로토콜) 서버를 생성하는 도구로, AI 어시스턴트가 API와 상호 작용할 수 있도록 지원합니다. 특정 API 또는 서비스에 맞춰 자체 브랜드 및 맞춤형 MCP를 생성하세요 .

개요

이 프로젝트는 OpenAPI 사양을 MCP 도구로 변환하는 동적 MCP 서버를 생성합니다. 모델 컨텍스트 프로토콜을 통해 REST API와 AI 어시스턴트를 원활하게 통합하여 모든 API를 AI가 접근 가능한 도구로 변환합니다.

특징

파일 또는 HTTP/HTTPS URL에서 OpenAPI 사양의 동적 로딩
파일 또는 HTTP/HTTPS URL에서 로드된 OpenAPI 오버레이 지원
MCP 도구에 대한 OpenAPI 작업의 사용자 정의 가능한 매핑
operationId 및 URL 경로 모두에 대해 glob 패턴을 사용하여 작업의 고급 필터링
형식 보존 및 위치 메타데이터를 통한 포괄적인 매개변수 처리
API 인증 처리
MCP 서버를 구성하는 데 사용되는 OpenAPI 메타데이터(제목, 버전, 설명)
계층적 설명 대체(작업 설명 → 작업 요약 → 경로 요약)
환경 변수 및 CLI를 통한 사용자 정의 HTTP 헤더 지원
API 요청 추적 및 식별을 위한 X-MCP 헤더
도구 이름과 설명을 재정의하기 위해 경로 수준에서 사용자 정의 x-mcp 확장 지원

AI 어시스턴트와 함께 사용

이 도구는 AI 어시스턴트가 OpenAPI 사양에 정의된 API와 상호 작용할 수 있도록 MCP 서버를 생성합니다. 이 도구를 사용하는 주요 방법은 AI 어시스턴트를 MCP 도구로 직접 실행하도록 구성하는 것입니다.

Claude Desktop 설정

컴퓨터에 Node.js가 설치되어 있는지 확인하세요.
Claude Desktop을 열고 설정 > 개발자로 이동하세요.
구성 파일을 편집합니다(파일이 없으면 새로 생성됩니다).
- macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
- Windows: %APPDATA%\Claude\claude_desktop_config.json
다음 구성을 추가합니다(필요에 따라 사용자 정의):

지엑스피1

Claude Desktop을 다시 시작하세요
이제 채팅 입력란에 망치 아이콘이 표시됩니다. 망치 아이콘을 클릭하여 API 도구에 접속하세요.

구성 사용자 정의

다양한 옵션으로 MCP 서버를 사용자 정의하려면 args 배열을 조정할 수 있습니다.

{
  "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"
    }
  ]
}

커서를 다시 시작하거나 창을 다시 로드하세요

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 경로의 쉼표로 구분된 목록(글로브 패턴 지원, 허용 목록 사용 시 무시됨)
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 : 모든 API 요청에 X-MCP: 1 헤더를 추가하는 것을 비활성화하려면 true 로 설정합니다.
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

나만의 버전 사용자 지정 및 게시

이 저장소를 기반으로 MCP 서버에 대한 맞춤형 OpenAPI를 생성할 수 있습니다. 이 섹션에서는 저장소를 포크하고, 특정 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 워크플로 사용자 지정

이 저장소에는 npm에 자동 게시하는 GitHub Actions 워크플로가 포함되어 있습니다. 포크된 저장소에 맞게 사용자 지정하려면 다음을 수행하세요.

워크플로 이름 업데이트 : 원하는 경우 .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_TOKEN 이라는 이름의 GitHub 비밀로 npm 토큰을 추가합니다.

맞춤형 패키지 게시

저장소를 사용자 지정한 후:

태그 생성 및 푸시 :
# 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

구성 섹션에 설명된 대로 환경 변수나 명령줄 옵션을 통해 기본 설정을 재정의할 수 있습니다.

특허

MIT

OpenAPI to MCP Server

Integrations