anyapi-mcp-server

API가 있다면, MCP로 연결할 수 있습니다.

기존의 MCP 서버들은 몇 개의 엔드포인트를 직접 선택하여 제공하므로, 누군가가 "충분하다"고 결정한 하위 집합에 갇히게 됩니다. 전체 API를 사용할 수 있는데 왜 일부만 사용하시나요?

anyapi-mcp-server는 모든 REST API를 Claude, Cursor 및 기타 LLM 기반 도구와 같은 AI 어시스턴트에 연결하는 범용 MCP 서버입니다. OpenAPI 사양이나 Postman 컬렉션을 지정하기만 하면 됩니다. API가 제공하는 모든 엔드포인트를 GraphQL 스타일의 필드 선택 및 자동 스키마 추론과 함께 즉시 사용할 수 있습니다. 사용자 지정 서버 코드나 인위적인 제한은 없습니다.

빠른 시작

1. 설치

npm install -g anyapi-mcp-server

2. MCP 클라이언트에 추가 (Cursor, Claude Desktop 등)

{
  "mcpServers": {
    "your-api": {
      "command": "npx",
      "args": [
        "-y",
        "anyapi-mcp-server",
        "--name", "your-api",
        "--spec", "path/to/openapi.json",
        "--base-url", "https://api.example.com",
        "--header", "Authorization: Bearer ${API_KEY}"
      ],
      "env": {
        "API_KEY": "your-api-key"
      }
    }
  }
}

3. 도구 사용 — list_api로 엔드포인트를 탐색하고, call_api로 스키마를 검사하며, query_api로 데이터를 가져옵니다.

제공자 예시

인기 있는 API를 위한 즉시 사용 가능한 구성:

이 구성들은 OpenAPI 또는 Postman 사양이 있는 모든 API에서 작동합니다. 위 예시는 단지 예시일 뿐입니다. Stripe, Twilio, Shopify, HubSpot 등 REST API가 있는 모든 서비스에서 동일하게 작동합니다.

CLI 참조

필수 플래그

선택적 플래그

OAuth 플래그

정적 토큰 대신 OAuth 2.0을 사용하는 API용입니다. 세 가지 필수 플래그 중 하나라도 제공되면 세 가지 모두가 필요합니다. 모든 플래그는 ${ENV_VAR}을 지원합니다.

전체 OAuth 예시는 Google Workspace 가이드를 참조하세요.

도구

이 서버는 4개의 도구(OAuth 구성 시 auth 포함)를 노출합니다:

list_api — 엔드포인트 탐색

API가 제공하는 기능을 확인합니다. 인자 없이 호출하면 모든 카테고리를 볼 수 있고, category를 제공하면 태그별 엔드포인트를 나열하며, search를 사용하면 키워드로 엔드포인트를 찾을 수 있습니다.

call_api — 엔드포인트 검사

실제 HTTP 요청을 수행하고 데이터 자체가 아닌 추론된 GraphQL 스키마(SDL)를 반환합니다. 이를 사용하여 응답 형태를 파악하고 query_api에 복사할 수 있는 suggestedQueries를 얻으세요. 또한 필드별 토큰 비용(fieldTokenCosts)과 캐시 재사용을 위한 dataKey를 반환합니다. PUT/PATCH 요청의 경우 자동으로 쓰기 전 백업을 생성합니다(backupDataKey 반환). 대용량 페이로드를 위한 bodyFile을 지원하며 감지된 자리 표시자 값이 포함된 요청은 차단합니다.

query_api — 데이터 가져오기

데이터를 가져오고 GraphQL 쿼리를 통해 선택한 필드만 반환합니다. 읽기 및 쓰기(POST/PUT/DELETE/PATCH에 대한 뮤테이션)를 모두 지원합니다. call_api에서 얻은 dataKey를 전달하여 HTTP 호출 없이 캐시된 데이터를 재사용하세요.

# Read
{ items { id name status } _count }

# Write
mutation { post_endpoint(input: { name: "example" }) { id } }

주요 매개변수:

• maxTokens — 응답에 대한 토큰 예산입니다. 배열은 이에 맞춰 잘립니다. 이 설정이나 unlimited가 없으면 약 10k 토큰을 초과하는 응답은 거부됩니다.

• unlimited — 토큰 예산 제한 없이 전체 응답을 반환하려면 true로 설정합니다.

• dataKey — 이전 call_api 또는 query_api 응답에서 캐시된 데이터를 재사용합니다.

• jsonFilter — GraphQL 쿼리 후 중첩된 값을 추출하기 위한 점(dot) 경로 (예: "data[].attributes.name").

• bodyFile — 요청 본문으로 사용할 JSON 파일의 절대 경로 ( body와 상호 배타적). 인라인으로 보낼 수 없는 대용량 페이로드에 사용하세요.

• skipBackup — PUT/PATCH 요청에 대한 자동 쓰기 전 백업을 건너뜁니다 (기본값: false).

explain_api — 문서 읽기

HTTP 요청을 수행하지 않고 엔드포인트에 대한 사양 문서(매개변수, 요청 본문 스키마, 응답 코드)를 반환합니다.

auth — OAuth 인증

--oauth-* 플래그가 구성된 경우에만 사용할 수 있습니다. OAuth 흐름을 관리합니다:

• action: "start" — 권한 부여 URL을 반환하거나(또는 client_credentials를 위해 자격 증명 교환)

• action: "exchange" — 권한 부여 코드 흐름을 완료합니다 (콜백은 자동으로 캡처됨)

• action: "status" — 현재 토큰 상태를 표시합니다

토큰은 자동으로 유지되고 새로 고쳐집니다.

일반적인 워크플로우

list_api          → discover what's available
     ↓
explain_api       → read the docs for an endpoint
     ↓
call_api          → inspect the response schema (returns dataKey)
     ↓
query_api         → fetch exactly the fields you need (pass dataKey for zero HTTP calls)
     ↓
query_api         → re-query with different fields using the same dataKey

작동 방식

OpenAPI/Postman spec
        │
        ▼
   ┌─────────┐  ┌─────────────┐  ┌──────────┐  ┌───────────┐
   │list_api │  │ explain_api │  │ call_api │  │ query_api │
   │(browse) │  │   (docs)    │  │ (schema) │  │  (data)   │
   └─────────┘  └─────────────┘  └──────────┘  └───────────┘
        │          │ no HTTP          │               │
        ▼          ▼ request          ▼               ▼
   Spec index   Spec index     REST API call    dataKey cache
   (tags,       (params,       (with retry)     hit → no HTTP
    paths)       responses,         │            miss → fetch
                 body schema)       ▼               │
                               Infer schema +       ▼
                               return dataKey   Execute GraphQL
                                                + token budget
                                                  truncation

기능

• 모든 REST API — OpenAPI(JSON/YAML) 또는 Postman Collection v2.x 사양을 파일이나 URL로 제공

• 원격 사양 캐싱 — HTTPS 사양은 한 번 가져온 후 ~/.cache/anyapi-mcp/에 캐시됨

• GraphQL 필드 선택 — 모든 응답에서 필요한 필드만 쿼리

• 스키마 추론 — 라이브 API 응답에서 자동으로 GraphQL 스키마 구축

• 다중 샘플 병합 — 더 풍부한 스키마를 위해 최대 10개의 배열 요소 샘플링

• 뮤테이션 지원 — 쓰기 작업은 OpenAPI 본문 스키마에서 유형이 지정된 GraphQL 뮤테이션을 가져옴

• 스마트 제안 — call_api는 추론된 스키마를 기반으로 즉시 사용 가능한 쿼리를 반환

• 응답 캐싱 — 5분 TTL이 있는 파일 시스템 기반 캐시; dataKey 토큰을 통해 query_api가 HTTP 호출 없이 데이터 재사용 가능

• 토큰 예산 — query_api는 기본적으로 약 10k 토큰 안전 제한을 적용; maxTokens를 사용하여 가장 깊고 큰 배열을 잘라내거나, 전체 응답을 위해 unlimited: true 사용

• 필드별 토큰 비용 — call_api는 LLM이 정보에 입각한 필드 선택을 할 수 있도록 fieldTokenCosts 트리를 반환

• 속도 제한 추적 — X-RateLimit-* 헤더를 파싱하고 제한이 거의 소진되었을 때 경고

• 페이지네이션 감지 — 응답에서 커서, 다음 페이지 토큰 및 링크 기반 페이지네이션 패턴 자동 감지

• JSON 필터 — query_api는 쿼리 후 추출을 위한 jsonFilter 점 경로를 허용 (예: "data[].name")

• 지수 백오프 재시도 — 429/5xx 오류에 대해 지수 백오프 및 Retry-After 지원을 통한 자동 재시도

• 다중 형식 — JSON, XML, CSV 및 일반 텍스트 응답 파싱

• 안전한 쓰기 — PUT/PATCH 요청은 쓰기 전에 자동으로 리소스 스냅샷을 생성(backupDataKey); 자리 표시자 값(예: PLACEHOLDER, TODO, file://)은 전송 전 감지 및 차단됨

• 파일 기반 본문 — bodyFile 매개변수는 JSON 파일의 절대 경로를 허용하여 인라인으로 보낼 수 없는 대용량 페이로드 지원

• 풍부한 오류 정보 — 상태별 제안 및 자체 수정을 위한 사양 컨텍스트가 포함된 구조화된 오류 메시지

• OAuth 2.0 — 자동 토큰 새로 고침이 포함된 권한 부여 코드(PKCE 포함) 및 클라이언트 자격 증명 흐름

• 환경 변수 보간 — 기본 URL, 헤더 및 사양 경로에서 ${ENV_VAR} 지원

• 요청 로깅 — 민감한 헤더 마스킹이 포함된 선택적 NDJSON 로그

지원되는 사양 형식

• OpenAPI 3.x (JSON 또는 YAML)

• OpenAPI 2.0 / Swagger (JSON 또는 YAML)

• Postman Collection v2.x (JSON)

라이선스

독점 비상업적 라이선스. 개인 및 교육용으로 무료입니다. 상업적 사용은 서면 허가가 필요합니다. 자세한 내용은 LICENSE를 참조하세요.