LLM Router MCP

Claude Code를 팀 리더로, GPT/Gemini를 전문가 팀으로 활용하는 MCP 서버

개요

LLM Router MCP는 Claude Code가 팀 리더 역할을 하며, GPT/Gemini 전문가에게 업무를 위임하는 MCP 서버입니다.

Note: Claude 모델은 MCP를 통해 호출되지 않습니다. Claude Code가 직접 Claude 역할을 수행하므로, 중첩 세션 문제를 피하면서 진정한 다중 LLM 협업이 가능합니다.

주요 특징

• 멀티 LLM 협업: Claude Code(리더) + GPT/Gemini 전문가 협업

• 역할 분담: implementer(codex)만 코드 변경 가능, 나머지 17명은 read-only로 강제

• 자동 폴백: Rate limit 발생 시 자동으로 다른 전문가로 전환

• 병렬 위임: delegate_task로 GPT 에이전트 1~3명에게 구현 작업 병렬 위임

• 중재형 토론: 중재자가 2라운드 패널 토론을 진행하고 최종 요약 반환

• 백그라운드 실행: 장시간 작업을 백그라운드에서 비동기 실행

• HUD Statusline: 실시간 비용, 컨텍스트, 전문가 활동 모니터링

Related MCP server: Gemini Collaboration MCP Server

빠른 시작

AI로 다른 프로젝트에 적용시키기

다른 프로젝트에서 AI에게 아래처럼 요청하면 글로벌 CLI 설치와 Claude Code MCP 등록까지 진행하도록 유도할 수 있습니다.

예시 프롬프트:

LLM Router MCP를 npm 글로벌 설치 방식으로 설치하고 Claude Code에 등록해줘.
프로젝트 CLAUDE.md는 300줄 이내로 유지해야 하니, 공용 사용법 문서는 별도 참조 문서로 연결해줘.

AI가 수행해야 하는 적용 작업:

1. npm install -g llm-router-mcp 실행

2. custommcp install로 Claude Code MCP 설정 자동 등록

3. custommcp doctor로 Node.js, MCP 등록, codex, gemini CLI 상태 확인

4. 대상 프로젝트의 CLAUDE.md에 공용 템플릿 구조 반영

5. 프로젝트 CLAUDE.md에는 플러그인 사용 시 plugin/docs/USAGE.md를 읽으라고 적고, 프로젝트 고유 규칙만 유지

6. 설치 후 llm_router_health 등으로 연결 확인

1. 설치

npm install -g llm-router-mcp
custommcp install
custommcp doctor

custommcp install은 ~/.claude/settings.json을 백업한 뒤 llm-router-mcp MCP 서버를 자동 등록합니다. 기존 llm-router-mcp 등록이 있으면 현재 설치 경로로 교체합니다. 전역 설치 단계에서는 레거시 CLIProxy 설정 스크립트를 자동 실행하지 않습니다. Claude Code 등록과 검증은 custommcp install과 custommcp doctor가 담당합니다.

2. CLI 도구 준비

터미널에서 사용할 LLM CLI 도구가 인증된 상태여야 합니다:

• codex — OpenAI Codex CLI (GPT 전문가 11명). codex login으로 인증

• agy — Antigravity CLI (Gemini 전문가 7명). 최초 실행 시 브라우저 인증

Gemini CLI(@google/gemini-cli)는 2026-06-18 공식 종료되어 더 이상 쓰지 않습니다. Google 계열은 후속작인 Antigravity CLI(agy)로 전환됐습니다.

claude CLI는 선택입니다. consult_expert에 model: "opus"를 명시할 때만 쓰이며, 사용자 본인의 Claude 구독 한도를 소모합니다. 설치돼 있지 않아도 나머지 기능은 정상 동작합니다.

설치 확인:

npm run probe        # 세 CLI 전부에 실제로 물어봐서 검증

3. 환경변수 설정 (선택)

EXA_API_KEY=your_exa_api_key        # 선택: 웹 검색
CONTEXT7_API_KEY=your_key           # 선택: 라이브러리 문서
CLI_CODEX_PATH=codex                # 선택: PATH에 없을 때만 지정
CLI_AGY_PATH=agy                    # 선택: PATH에 없을 때만 지정
CLI_CLAUDE_PATH=claude              # 선택: opt-in 전용
CLAUDE_MAX_BUDGET_USD=1.0           # 선택: claude -p 호출당 비용 상한

4. Claude Code 연동

custommcp install이 Claude Code 설정을 자동으로 등록합니다. 프로젝트별 사용 규칙을 빠르게 붙이고 싶으면 공용 템플릿 plugin/templates/CLAUDE.md를 프로젝트 루트 CLAUDE.md의 시작점으로 사용하고, 플러그인 상세 운영 규칙은 plugin/docs/USAGE.md를 참조하면 됩니다.

5. 로컬 개발 폴더명

저장소와 npm 패키지 이름은 llm-router-mcp입니다. 로컬 개발 폴더도 llm-router-mcp/를 권장합니다. CLI 명령어 custommcp는 기존 사용자 호환성을 위해 유지합니다.

역할 분담

전문가 18명 중 implementer 하나만 쓰기 권한을 갖습니다. 나머지 17명은 CLI 레벨에서 read-only가 강제되므로, 프롬프트로 지시해도 파일을 고칠 수 없습니다. 쓰기가 필요하면 delegate_task를 쓰세요.

• 모든 CLI 도구가 파일 경로를 넘기면 직접 읽음 (토큰 절약)

• 2명 이상 전문가 호출 시 반드시 병렬 (consult_experts_parallel)

전문가 시스템

GPT/Gemini 전문가만 MCP를 통해 호출됩니다. Claude 관련 분석/판단은 Claude Code가 직접 수행합니다.

기본 전문가 (5명)

특화 전문가 (7명)

동적 페르소나 전문가 (4명)

토론 시 AI가 자동으로 역할을 부여하는 빈 슬롯 (GPT/Gemini only):

토론 중재자 (1명)

핵심 도구

전문가 상담

작업 위임

백그라운드 실행

워크플로우

코드 분석

Git

기타

훅 시스템

38개 내장 훅으로 동작 확장:

핵심 훅

안정성 훅

UX 훅

스킬 시스템

15개 내장 스킬이 자연어 요청을 인식하여 자동으로 호출됩니다:

중재형 토론

중재자가 안건을 모든 참여자에게 병렬로 던지고, 1차 응답을 종합한 뒤 다시 한 번 병렬 재질의합니다.

moderated_debate({
  agenda: "마이크로서비스 vs 모놀리식",
  participant_count: 3,
  repeat_count: 1
})

직접 페르소나를 주고 싶으면 participants를 넘기고, 아니면 participant_count(2-4)만 넘겨 자동 페르소나 배정을 사용합니다.

설계 위임 스킬

llm-plan과 llm-planAll은 바로 구현에 들어가지 않고, 설계 검토 게이트를 먼저 통과합니다.

llm-plan

흐름:

1. Claude가 plan 모드에서 설계와 GPT 서브태스크를 작성

2. Claude가 Agent 도구로 설계 검토를 수행

3. GPT 설계 전문가가 2차 검토

4. 두 검토를 통과하면 사용자 확인 후 GPT 에이전트 1~3명에게 구현 위임

5. 구현 결과를 멀티 관점으로 리뷰

특징:

• Claude는 설계와 리뷰만 수행

• 실제 코드 변경은 GPT만 수행

• 설계 검토 중 이슈가 나오면 plan으로 돌아가 수정 후 재검토

llm-planAll

흐름:

1. Claude가 plan 모드에서 자신의 작업과 GPT 작업을 분리해 설계

2. Claude가 Agent 도구로 설계 검토를 수행

3. GPT 설계 전문가가 2차 검토

4. 두 검토를 통과하면 사용자 확인

5. GPT 작업을 먼저 백그라운드 위임하고, Claude도 자기 파일 범위에서 동시 구현

6. 전체 결과를 통합 리뷰

특징:

• Claude와 GPT가 같은 파일을 수정하면 안 됨

• Claude 작업과 GPT 작업은 독립적이어야 함

• 설계 검토 전에는 위임이나 구현을 시작하지 않음

Think Mode

복잡한 문제에 대한 깊은 분석:

모델별 타임아웃

프로젝트 구조

llm-router-mcp/
├── src/
│   ├── index.ts              # MCP 서버 진입점
│   ├── experts/              # 전문가 정의 (11개 + 토론 전용 슬롯)
│   ├── tools/                # MCP 도구 (109개)
│   ├── hooks/builtin/        # 내장 훅 (38개)
│   ├── hud/                  # HUD 상태 관리
│   ├── features/             # 기능 모듈
│   │   ├── skill-system/     # 스킬 시스템
│   │   ├── mcp-loader/       # MCP 서버 관리
│   │   └── boulder-state/    # 볼더 상태 관리
│   ├── services/             # 핵심 서비스
│   │   ├── expert-router.ts  # 전문가 라우팅
│   │   ├── cliproxy-client.ts # CLI 도구 오케스트레이터
│   │   ├── providers/         # CLI 프로바이더 (Gemini/Codex only)
│   │   └── background-manager.ts # 백그라운드 작업 관리
│   └── utils/                # 유틸리티
├── plugin/skills/            # 내장 스킬 (15개)
└── dist/                     # 빌드 출력

CLI 도구 연동

터미널에 설치된 CLI 도구를 child_process.spawn()으로 직접 호출합니다.

지원 CLI 도구

• agy — Gemini 3.1 Pro / 3.6 Flash 등 (리뷰/분석 전용)

• codex — GPT 계열 모델 (implementer만 코드 변경 가능)

Note: claude CLI는 사용하지 않습니다. Claude Code가 직접 Claude 역할을 수행합니다.

사전 요구사항

각 CLI 도구가 터미널에서 인증 완료된 상태여야 합니다. CLI 도구 경로는 .env에서 설정 가능합니다 (PATH에 있으면 생략 가능):

CLI_AGY_PATH=agy
CLI_CODEX_PATH=codex

문제 해결

CLI 도구 연결 실패

# CLI 도구 설치 확인
gemini --version
codex --version

# 인증 상태 확인
gemini auth status
codex auth status

Rate Limit

시스템이 자동으로:

1. HTTP 429 및 에러 메시지 패턴 감지

2. 모델을 제한 상태로 표시

3. 폴백 전문가로 라우팅

4. 지수 백오프로 재시도

영감을 받은 프로젝트

• oh-my-opencode

• oh-my-claudecode

라이선스

MIT