OpenAPI to Model Context Protocol (MCP)

License: MIT

Repo Size

Last Commit

Open Issues

Python version

OpenAPI-MCP 프록시는 OpenAPI 사양을 MCP 도구로 변환하여, AI 에이전트가 사용자 정의 래퍼 없이 외부 API에 접근할 수 있게 합니다!

AI 에이전트와 외부 API 간의 격차 해소하기

OpenAPI to Model Context Protocol (MCP) 프록시 서버는 OpenAPI 사양을 표준화된 MCP 도구, 리소스, 및 프롬프트로 동적으로 변환함으로써 AI 에이전트와 외부 API 사이의 격차를 해소합니다. 이를 통해 사용자 정의 API 래퍼가 필요 없어 통합이 간소화됩니다.

공식 MCP 패턴과 모범 사례를 따라 FastMCP로 구축된 이 서버는 다음 기능을 제공합니다:

• ✅ 공식 FastMCP 통합: 최적의 성능을 위해 최신 FastMCP 프레임워크 사용

• ✅ 올바른 MCP 전송: stdio, SSE, 스트리밍 가능한 HTTP 전송 지원

• ✅ 모듈형 아키텍처: 의존성 주입(dependency injection)을 통한 관심사 분리

• ✅ 프로덕션 준비 완료: 강력한 오류 처리, 포괄적인 로깅 및 타입 안정성

• 저장소: https://github.com/gujord/OpenAPI-MCP

유용하다고 생각하시면 GitHub에서 별점을 부탁드립니다!

주요 기능

핵심 기능

• FastMCP Transport: stdio에 최적화되어 있으며, 인기 있는 LLM 오케스트레이터와 별도의 설정 없이 바로 작동합니다.
• OpenAPI 통합: OpenAPI 작업을 파싱하여 호출 가능한 도구(tool)로 등록합니다.
• 리소스 등록: OpenAPI 컴포넌트 스키마를 정의된 URI를 가진 리소스 객체로 자동 변환합니다.
• 프롬프트 생성: API 작업에 기반한 컨텍스트 프롬프트를 생성하여 LLM이 API를 사용하도록 안내합니다.
• 듀얼 인증: OAuth2 Client Credentials 플로우와 사용자 이름/비밀번호 인증을 모두 지원하며, 토큰 캐싱이 자동화됩니다.
• MCP HTTP Transport: JSON-RPC 2.0 기반의 SSE(Server-Sent Events)를 사용하는 공식 MCP 규격 준수 HTTP 스트리밍 전송 방식입니다.
• Server-Sent Events (SSE): 레거시 스트리밍 지원 (사용 중단됨 - MCP HTTP transport 사용 권장).
• JSON-RPC 2.0 지원: 완벽하게 호환되는 요청/응답 구조를 제공합니다.

고급 기능

• 모듈식 아키텍처: 인증, 요청 처리, 도구 생성에 전용 모듈을 할당하여 관심사 분리(separation of concerns)가 명확합니다.
• 견고한 오류 처리: 적절한 JSON-RPC 오류 코드와 구조화된 오류 응답을 갖춘 포괄적인 예외 계층 구조를 제공합니다.
• 자동 메타데이터: OpenAPI 사양으로부터 도구 이름, 요약(summary), 스키마를 추출합니다.
• 정제된 도구 이름 (Sanitized Tool Names): MCP의 이름 제약 조건과의 호환성을 보장합니다.
• 유연한 매개변수 파싱: 쿼리 문자열, JSON, 쉼표로 구분된 형식을 지원하며 지능적인 타입 변환을 수행합니다.
• 향상된 매개변수 처리: 매개변수를 올바른 데이터 타입으로 자동 변환하고 유효성 검사를 수행합니다.
• 확장된 도구 메타데이터: 상세한 매개변수 정보, 응답 스키마, API 분류를 포함합니다.
• CRUD 작업 감지: 생성(Create), 읽기(Read), 업데이트(Update), 삭제(Delete) 작업을 자동으로 식별하고 예시 프롬프트를 생성합니다.
• MCP 규격 준수 스트리밍: 적절한 세션 관리를 갖춘 실시간 스트리밍을 위한 공식 MCP HTTP 전송 방식을 제공합니다.

개발자 경험 (Developer Experience)

• 설정 관리 (Configuration Management): 유효성 검사 및 기본값을 포함한 중앙 집중식 환경 변수 처리.
• 종합 로깅 (Comprehensive Logging): 디버깅 및 모니터링을 위한 적절한 레벨의 구조화된 로깅.
• 타입 안정성 (Type Safety): 코드베이스 전반에 걸친 완전한 타입 힌트 및 유효성 검사.
• 확장 가능한 설계 (Extensible Design): 쉬운 커스터마이징 및 테스트를 위한 Factory 패턴과 의존성 주입(Dependency Injection).

🚀 빠른 시작 (Quick Start)

설치 (Installation)

옵션 1: uvx 사용 (권장)

# 설치 없이 바로 실행
uvx openapi-mcp-proxy

...

옵션 2: pip 사용

pip install openapi-mcp-proxy

# 그리고 실행
...

옵션 3: 소스에서 설치 (From source)

git clone https://github.com/gujord/OpenAPI-MCP.git
cd OpenAPI-MCP
python3.12 -m venv venv
...

🎯 간단한 사용법 (Simple Usage)

빠른 테스트 (노르웨이 날씨 API)

# uvx 사용
OPENAPI_URL="https://api.met.no/weatherapi/locationforecast/2.0/swagger" \
SERVER_NAME="weather" \
...

HTTP 전송 (Claude Desktop에 권장)

# HTTP 전송으로 날씨 API 시작
OPENAPI_URL="https://api.met.no/weatherapi/locationforecast/2.0/swagger" \
SERVER_NAME="weather" \
...

🔗 Claude Desktop 설정 (Claude Desktop Setup)

1. 제공된 구성 복사:

cp claude_desktop_config.json ~/Library/Application\ Support/Claude/claude_desktop_config.json

2. 날씨 서버 시작:

OPENAPI_URL="https://api.met.no/weatherapi/locationforecast/2.0/swagger" \
SERVER_NAME="weather" \
MCP_HTTP_ENABLED="true" \
...

3. Claude Desktop에서 테스트:

• 질문: *

Docker를 이용한 빠른 시작:

# 모든 서비스 시작하기 (날씨 + 펫스토어)
./docker-start.sh

...

이 명령어는 자동으로 다음을 실행합니다:

• 포트 8001의 날씨 API
• 포트 8002의 펫스토어 API

⚙️ 고급 설정

Claude Desktop / Cursor / Windsurf

HTTP 전송 (권장):

제공된 설정 파일을 사용하세요:

cp claude_desktop_config.json ~/Library/Application\ Support/Claude/claude_desktop_config.json

또는 수동으로 생성하세요:

{
  "mcpServers": {
    "weather": {
...

Stdio 전송 (대안):

{
  "mcpServers": {
    "weather": {
...

참고: /full/path/to/OpenAPI-MCP를 실제 설치 경로로 교체하세요.

로컬 스펙 및 사용자 지정 헤더 사용 시

{
  "mcpServers": {
    "local_api": {
...

사용자 이름/비밀번호 인증 사용 시

{
  "mcpServers": {
    "secure_api": {
...

OAuth2 인증 사용 시

{
  "mcpServers": {
    "oauth_api": {
...

MCP HTTP 전송을 이용한 다중 API 서버 설정

여러 개의 OpenAPI 서비스를 동시에 실행하도록 구성하세요:

{
  "mcpServers": {
    "weather": {
...

이 설정을 통해 Claude는 weather_get__compact 및 petstore_addPet과 같은 명확한 도구 이름으로 날씨 데이터와 펫스토어 API 도구를 동시에 사용할 수 있게 됩니다.

MCP HTTP 전송을 이용한 단일 API 서버 설정

단일 API 서비스를 위한 경우:

표준 SSE 구성:

{
  "mcpServers": {
    "openapi_service": {
...

스트리밍 가능한 HTTP 구성:

{
  "mcpServers": {
    "openapi_service": {
...

디버깅 기능 포함 (개발용):

{
  "mcpServers": {
    "openapi_service": {
...

사용자 지정 전송 전략 포함:

{
  "mcpServers": {
    "openapi_service": {
...

레거시 SSE 스트리밍 사용 (사용 중단)

{
  "mcpServers": {
    "streaming_api": {
...

이 구성을 다음 파일에 적용하세요:

• Cursor: ~/.cursor/mcp.json
• Windsurf: ~/.codeium/windsurf/mcp_config.json
• Claude Desktop: ~/Library/Application Support/Claude/claude_desktop_config.json

full_path_to_openapi_mcp를 실제 설치 경로로 교체하세요.

여러 API에 대한 빠른 설정 (Quick Setup for Multiple APIs)

제공된 예시 설정을 복사하세요:

cp claude_desktop_config.json ~/Library/Application\ Support/Claude/claude_desktop_config.json

두 서비스 모두 시작하세요:

# Terminal 1
source venv/bin/activate && \
OPENAPI_URL="https://api.met.no/weatherapi/locationforecast/2.0/swagger" \
...

결과: Claude가 접두사(prefixed)가 지정된 도구 이름으로 날씨 및 petstore API 모두에 접근할 수 있게 됩니다.

환경 설정 (Environment Configuration)

핵심 설정 (Core Configuration)

OAuth2 인증

사용자 이름/비밀번호 인증

커스텀 인증 헤더

MCP HTTP 전송 (권장)

레거시 SSE 지원 (사용 중단)

📁 로컬 OpenAPI 사양 불러오기

이제 원격 URL을 요구하는 대신, 로컬 파일 시스템에서 OpenAPI 사양을 불러올 수 있습니다:

JSON 형식

source venv/bin/activate
OPENAPI_URL="./specs/my-api.json" \
SERVER_NAME="local_api" \
... 

YAML 형식

source venv/bin/activate
OPENAPI_URL="../shared/api.yaml" \
SERVER_NAME="local_api" \
...

절대 경로(Absolute Path)

source venv/bin/activate
OPENAPI_URL="/Users/myuser/projects/api-spec.json" \
SERVER_NAME="local_api" \
...

지원되는 형식(Supported Formats)

• JSON 파일: .json 확장자
• YAML 파일: .yaml 또는 .yml 확장자
• 상대 경로(Relative paths): ./path/to/spec.yaml, ../spec.json
• 절대 경로(Absolute paths): /full/path/to/spec.yaml

🔑 API 키 및 사용자 정의 헤더(API Key and Custom Headers)

사용자 정의 헤더가 필요한 API(API 키, 토큰 등) 지원:

JSON 형식 사용

source venv/bin/activate
MCP_AUTH_HEADERS='{"X-API-Key": "your-api-key", "X-Client-ID": "client123"' \
OPENAPI_URL="https://api.example.com/openapi.json" \
...

단순 형식(Simple Format) 사용

source venv/bin/activate
MCP_AUTH_HEADERS='X-API-Key=your-api-key,X-Client-ID=client123' \
OPENAPI_URL="https://api.example.com/openapi.json" \
...

일반적인 API 키 패턴(Common API Key Patterns)

• RapidAPI: MCP_AUTH_HEADERS='{"X-RapidAPI-Key": "your-key"}'
• 사용자 정의 Bearer: MCP_AUTH_HEADERS='{"Authorization": "Bearer custom-token"}'
• 다중 헤더(Multiple Headers): MCP_AUTH_HEADERS='{"X-API-Key": "key", "X-API-Secret": "secret"}'

로컬 스펙 + 사용자 정의 헤더

두 기능을 결합하여 개발에 사용:

source venv/bin/activate
OPENAPI_URL="./test/fixtures/api.json" \
MCP_AUTH_HEADERS='{"X-API-Key": "dev-key"}' \
...

🛠️ 예시 및 사용 사례(Examples & Use Cases)

노르웨이 날씨 API(Norwegian Weather API)

실제 날씨 데이터로 테스트 (인증 필요 없음):

# 날씨 서버 시작
source venv/bin/activate && \
OPENAPI_URL="https://api.met.no/weatherapi/locationforecast/2.0/swagger" \
...