kiwoom-plugin CLAUDE.md

kiwoom-plugin

키움증권 REST API를 Claude Code에 연결하는 것 전부를 담은 저장소. 플러그인 두 개 + MCP 서버 본체.

구조

kiwoom-plugin/
├── .claude-plugin/marketplace.json   마켓플레이스 (플러그인 2개 등록)
├── plugins/
│   ├── kiwoom/                        조회 전용 플러그인
│   │   ├── .claude-plugin/plugin.json
│   │   ├── .mcp.json                  서버를 uvx로 실행 (주문 없음)
│   │   └── skills/                    stock-research, portfolio-review, pnl-report,
│   │                                  market-scan, condition-search, kiwoom-setup
│   └── kiwoom-trader/                 조회 + 주문 플러그인
│       ├── .mcp.json                  서버를 --allow-orders로 실행
│       └── skills/                    위 6개 + place-order
├── server.json                       공식 MCP 레지스트리 매니페스트
└── server/                           MCP 서버 본체 (파이썬 패키지 kiwoom-mcp)
    ├── kiwoom_mcp/{cli,server,runner,policy}.py
    ├── tests/                         211개
    ├── pyproject.toml
    ├── Dockerfile / compose.yaml      헤드리스 컨테이너 (토큰 주입)
    └── README.md

세 저장소의 관계

• kiwoom-cli — 키움 API 236종 CLI. 안전장치(주문 확인 게이트, dry-run, 멱등키, envelope)가 전부 여기 있다. 서버는 이것을 감쌀 뿐 다시 구현하지 않는다.
• kiwoom-plugin (이 저장소) — 플러그인 + 스킬 + 서버.
• kiwoom-mcp — 서버를 담던 별도 저장소. 이 저장소로 흡수하고 삭제 중(로컬 삭제됨, GitHub는 수동 삭제 대기).

개발

cd server
pip install -e ".[dev]"
pytest tests/ -q          # 211개
ruff check kiwoom_mcp/ tests/

서버는 kiwoom-cli를 의존성으로 쓴다 (PyPI의 kiwoom-cli). 도구 표면이 kiwoom-cli의 명령 트리에서 나오므로, kiwoom-cli가 바뀌면 여기 테스트가 먼저 깨진다.

플러그인 배선 (중요)

두 플러그인의 .mcp.json은 서버를 PyPI에서 실행한다:

uvx --from "kiwoom-mcp==0.1.1" kiwoom-mcp [--allow-orders]

• 정확한 버전에 고정한다 (==0.1.1), 범위나 bare가 아니라. 진짜 제약은 "git 태그여야 한다"가 아니라 uvx 캐시 경로가 안정적이어야 한다는 것이다 — bare kiwoom-mcp는 새 릴리스가 나올 때마다 경로가 바뀌고, macOS는 키체인 접근을 바이너리 단위로 승인하므로 그때마다 승인 창이 다시 뜬다.
• .mcp.json이 고정하는 버전은 반드시 PyPI에 게시된 버전이어야 한다. 서버를 올렸으면: 버전 범프 → 빌드 → PyPI 게시 → 두 .mcp.json의 ==X.Y.Z를 갱신. 게시 전에 pin을 올리면 플러그인이 연결에 실패한다.
• 게시 전 검증이나 저장소 직접 실행은 git 형태를 쓴다: uvx --from "git+https://github.com/gejyn14/[email protected]#subdirectory=server" kiwoom-mcp (#subdirectory=server로 하위 디렉터리만 설치, uv가 지원함).