@10xtf/11st-seller-mcp

11번가(11st) Seller Open API를 144개의 개별 MCP 도구로 노출하는 MCP 서버입니다. stdio 전송 방식을 사용하며, 다양한 AI 코딩 도구(Claude Code, Cursor, Gemini, GitHub Copilot 등)에서 바로 호출할 수 있습니다.

도구 이름과 설명(description)은 영문으로 제공되지만, 파라미터 설명과 11st API 응답 페이로드는 한국어 그대로 유지됩니다(11st API 자체가 한국어 우선이기 때문). EUC-KR XML 응답은 UTF-8 JSON으로 자동 디코딩되어 반환됩니다.

사전 준비

1. Node.js 20 이상 (node --version으로 확인)
2. 11번가 OpenAPI 키: 셀러오피스에서 발급
3. 환경 변수 ELEVENST_OPENAPI_KEY 에 해당 키 지정

설치 방식은 모두 동일하게 npx -y @10xtf/11st-seller-mcp@latest 명령을 사용합니다. 글로벌 설치 없이 항상 최신 버전을 받아 실행합니다.

MCP 클라이언트별 설치 방법

1. Claude Code

Claude Code는 claude mcp add CLI 또는 설정 파일 편집 두 가지 방법을 지원합니다.

방법 A — CLI 사용 (권장)

claude mcp add 11st-seller \
  --env ELEVENST_OPENAPI_KEY=여기에_API_키_입력 \
  -- npx -y @10xtf/11st-seller-mcp@latest

스코프를 지정하려면 -s user(전역) 또는 -s project(현재 프로젝트의 .mcp.json)를 추가합니다.

claude mcp add 11st-seller -s user \
  --env ELEVENST_OPENAPI_KEY=... \
  -- npx -y @10xtf/11st-seller-mcp@latest

방법 B — 설정 파일 직접 편집

• 사용자 전역: ~/.claude.json
• 프로젝트 단위: 프로젝트 루트의 .mcp.json

{
  "mcpServers": {
    "11st-seller": {
      "command": "npx",
      "args": ["-y", "@10xtf/11st-seller-mcp@latest"],
      "env": {
        "ELEVENST_OPENAPI_KEY": "여기에_API_키_입력"
      }
    }
  }
}

확인: Claude Code 안에서 /mcp 명령으로 등록된 MCP 서버 상태를 볼 수 있습니다.

2. Cursor

Cursor는 mcp.json 설정 파일을 사용합니다.

• 사용자 전역: ~/.cursor/mcp.json
• 프로젝트 단위: 프로젝트 루트의 .cursor/mcp.json

{
  "mcpServers": {
    "11st-seller": {
      "command": "npx",
      "args": ["-y", "@10xtf/11st-seller-mcp@latest"],
      "env": {
        "ELEVENST_OPENAPI_KEY": "여기에_API_키_입력"
      }
    }
  }
}

저장 후 Cursor → Settings → MCP 패널에서 11st-seller가 green/connected 상태인지 확인합니다. 도구 목록에서 144개의 도구가 보이면 정상입니다.

3. Gemini (Gemini CLI / Code Assist)

Gemini CLI는 ~/.gemini/settings.json(전역) 또는 프로젝트의 .gemini/settings.json에 MCP 서버를 등록합니다.

{
  "mcpServers": {
    "11st-seller": {
      "command": "npx",
      "args": ["-y", "@10xtf/11st-seller-mcp@latest"],
      "env": {
        "ELEVENST_OPENAPI_KEY": "여기에_API_키_입력"
      },
      "timeout": 30000,
      "trust": false
    }
  }
}

설정 후 gemini 실행 → /mcp 명령으로 서버 상태와 도구 목록을 확인할 수 있습니다.

4. GitHub Copilot (VS Code의 Copilot Chat — Agent Mode)

GitHub Copilot의 Agent Mode는 워크스페이스 단위의 .vscode/mcp.json 파일을 통해 MCP 서버를 인식합니다.

프로젝트 루트에 .vscode/mcp.json 파일을 생성합니다.

{
  "servers": {
    "11st-seller": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@10xtf/11st-seller-mcp@latest"],
      "env": {
        "ELEVENST_OPENAPI_KEY": "여기에_API_키_입력"
      }
    }
  }
}

Copilot 설정 파일은 mcpServers가 아닌 servers 키를 사용한다는 점에 주의하세요. 또한 각 서버마다 "type": "stdio"를 명시해야 합니다.

전역 등록을 원하면 VS Code의 settings.json에 다음을 추가합니다.

{
  "github.copilot.chat.mcp.servers": {
    "11st-seller": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@10xtf/11st-seller-mcp@latest"],
      "env": {
        "ELEVENST_OPENAPI_KEY": "여기에_API_키_입력"
      }
    }
  }
}

VS Code Copilot Chat 패널을 Agent 모드로 전환한 뒤 도구 아이콘에서 11st-seller 의 144개 도구가 노출되는지 확인합니다.

환경 변수

| 이름 | 필수 | 기본값 | 설명 | | ----------------------- | ---- | ------------------------------ | ---------------------------------------------------------- | | ELEVENST_OPENAPI_KEY | 예 | — | 11번가 OpenAPI 키 (셀러오피스에서 발급). | | ELEVENST_API_BASE | 아니오 | https://api.11st.co.kr/rest | 베이스 URL 오버라이드(프록시/스테이징용). | | ELEVENST_TIMEOUT_MS | 아니오 | 30000 | 요청별 타임아웃(ms). | | MCP_LOG_LEVEL | 아니오 | info | debug | info | warn | error. 로그는 stderr 출력.|

동작 개요

• Transport: stdio 전용
• Encoding: 11번가 응답 XML(EUC-KR)을 iconv-lite로 디코딩 후 fast-xml-parser로 파싱. POST/PUT 본문은 EUC-KR XML로 다시 인코딩.
• Validation: 모든 입력은 zod 스키마로 검증되며, 실패 시 isError: true 와 함께 사람이 읽을 수 있는 메시지를 반환.
• Errors: 11번가의 result_code(0=결과 없음, 2=조회 범위 초과, 1000=점검 등)를 메시지로 매핑. HTTP 401/403 발생 시 API 키 점검 힌트 출력.
• Retry: HTTP 429 / 5xx / 네트워크 오류는 500ms 후 1회 자동 재시도(요청당 최대 1회).

도구 이름 규칙

도구 이름은 11번가 REST URL을 기반으로 domain_action 형식의 snake_case 로 생성됩니다.

| 11st URL | Method | Tool name | | -------------------------------------------------- | ------ | ---------------------------- | | /cateservice/category | GET | cate_category | | /prodmarketservice/prodmarket/stocks | POST | prodmarket_stocks | | /settlement/settlementList/[startTime]/[endTime] | GET | settlement_settlement_list | | /ordservices/complete/[ordNo] | GET | ord_complete |

이름·설명 오버라이드는 scripts/name-map.ts (apiSeq → metadata) 와 src/tools/overrides 에서 관리합니다. 수정 후에는 npm run codegen 을 실행해야 합니다.

개발

npm install
npm run codegen   # docs/11st_api_doc/*.md → src/tools/generated/*.ts
npm run typecheck
npm test          # vitest
npm run dev       # tsx src/index.ts
npm run build     # tsup → bin/11st-seller-mcp.js

로컬 패키지로 e2e 스모크 테스트를 하려면:

npm pack
ELEVENST_OPENAPI_KEY=... npx ./10xtf-11st-seller-mcp-0.0.1.tgz

트러블슈팅

| 증상 | 원인 / 해결 | | -------------------------------------------- | ------------------------------------------------------------------------------------------------- | | 도구 목록이 비어 있음 | API 키 미설정 또는 stdout에 로그가 섞여 들어가는 경우. MCP_LOG_LEVEL=debug 로 stderr 확인. | | HTTP 401 / HTTP 403 | ELEVENST_OPENAPI_KEY 가 잘못되었거나 만료. 셀러오피스에서 키 재발급. | | result_code: 1000 | 11번가 점검 시간. 잠시 후 재시도. | | Copilot에서 서버가 안 보임 | mcp.json 의 키가 mcpServers 가 아닌 servers 인지 확인. "type": "stdio" 누락 여부 확인. | | npx 실행 지연 | 처음 1회는 패키지를 받아오느라 느릴 수 있음. CI 등에서는 npm i -g @10xtf/11st-seller-mcp@latest 후 command: 11st-seller-mcp 사용 권장. |

License

Apache-2.0. LICENSE 참고.