ollama-mcp

Anthropic 기반 Claude Code 세션에서 Ollama 기반 Claude Code 세션으로 작업을 위임하세요 — 두 세션이 환경 변수를 공유하지 않으면서도 가능합니다.

ollama launch claude --model <model>는 ANTHROPIC_* 변수를 쉘에 내보내는 방식으로 작동합니다. 그래서 일반적으로 자체 터미널이 필요합니다: 변수는 프로세스 전체에 적용되므로 하나의 쉘은 "Anthropic" 또는 "Ollama" 중 하나만 될 수 있으며, 둘 다 동시에 될 수 없습니다.

이 MCP 서버는 각 위임된 세션을 명시적으로 구성된 환경을 가진 자식 프로세스로 생성합니다. Opus 세션은 자체 자격 증명과 모델 설정을 유지하고, 위임된 세션은 Ollama의 설정을 가져옵니다. 두 세션은 동일한 터미널에서 나란히 실행됩니다.

┌────────────────────────────┐
│  Claude Code (Opus)        │   your session, Anthropic credentials
│                            │
│   └─ mcp: ollama-mcp ──────┼──▶ spawn: claude -p   (fresh env)
└────────────────────────────┘         ANTHROPIC_BASE_URL=127.0.0.1:11434
                                       ANTHROPIC_AUTH_TOKEN=ollama
                                       → qwen3.5:397b-cloud

목차

• 작동 방식

• 사전 요구 사항

• 설치

• 설정

• 위임 모드

• 도구 참조

• 운영

• 작업 산출물

• 문제 해결

• 플랫폼 지원

• 보안 모델

• 개발

Related MCP server: codex-as-mcp

작동 방식

Ollama 서버는 Anthropic 호환 POST /v1/messages 엔드포인트를 제공하므로, Claude Code가 올바른 기본 URL을 가리키면 수정 없이 통신할 수 있습니다. 각 위임된 작업은 자체 프로세스에서 claude -p로 실행되며:

ANTHROPIC_BASE_URL=http://127.0.0.1:11434
ANTHROPIC_AUTH_TOKEN=ollama
ANTHROPIC_DEFAULT_OPUS_MODEL=<model>
ANTHROPIC_DEFAULT_SONNET_MODEL=<model>
ANTHROPIC_DEFAULT_HAIKU_MODEL=<model>
CLAUDE_CODE_SUBAGENT_MODEL=<model>

세 가지 모델 슬롯 모두 동일한 Ollama 모델을 가리키므로 별칭(opus, sonnet, haiku)과 위임자 내부에서 생성된 모든 하위 에이전트가 해당 모델로 연결되며, Anthropic 기본값으로 조용히 대체되지 않습니다.

자식 환경은 소규모 플랫폼별 허용 목록에서 구성됩니다. ANTHROPIC_*, CLAUDE_*, AWS_*, GOOGLE_*, AZURE_*, OPENAI_*, BEDROCK_*, VERTEX_*와 일치하는 모든 항목은 Ollama 값이 적용되기 전에 삭제되므로, 쉘에 남아 있는 ANTHROPIC_API_KEY가 위임된 실행으로 유출되거나 청구될 수 없습니다.

위임자는 --strict-mcp-config와 MCP 설정 없이 시작되므로, 시작 속도가 빠르고 이 서버를 재귀적으로 호출하는 것을 방지합니다.

사전 요구 사항

설치 전 구성 요소를 확인하세요:

node --version                              # v20 or newer
claude --version
curl -s http://127.0.0.1:11434/api/version  # {"version":"..."}
ollama list                                 # at least one model

클라우드 vs 로컬 모델. 태그가 :cloud인 모델은 Ollama의 인프라에서 실행되며 ollama signin이 필요합니다. 대부분의 노트북 메모리에 맞는 것보다 훨씬 강력하므로, 위임에 실용적인 선택입니다. 로컬 모델도 작동하며 컴퓨터를 떠나지 않습니다.

설치

npm으로 설치 (권장)

복제나 빌드가 필요 없음 — npx가 요청 시 가져옵니다:

claude mcp add ollama --scope user -- npx -y claude-ollama-delegate-mcp

또는 전역으로 설치하면 설정 CLI도 PATH에 추가됩니다:

npm install -g claude-ollama-delegate-mcp
claude mcp add ollama --scope user -- claude-ollama-delegate-mcp

소스에서 설치

git clone https://github.com/histonedev/claude-ollama-delegate-mcp.git
cd claude-ollama-delegate-mcp
npm install          # builds automatically via the prepare script
claude mcp add ollama --scope user -- node "$(pwd)/dist/index.js"

설정 CLI를 node dist/cli.js …로 실행하거나, npm link를 사용하여 ollama-mcp-config를 PATH에 추가합니다.

범위

--scope user는 모든 프로젝트에서 사용 가능하게 합니다. --scope project는 현재 저장소의 .mcp.json에 작성하여 협업자와 공유합니다. --scope local은 이 머신과 프로젝트로 제한합니다.

확인

claude mcp list        # ollama: ... - ✔ Connected

그런 다음 Claude Code 세션을 다시 시작하세요 — 도구 목록은 시작 시 읽힙니다.

설정

설정은 네 계층에서 확인되며, 나중 계층이 이전 계층보다 우선합니다:

1. 내장 기본값

2. 사용자 설정 — ~/.ollama-mcp/config.json ($OLLAMA_MCP_CONFIG로 경로 재정의 가능)

3. 프로젝트 설정 — 서버 작업 디렉토리의 ./ollama-mcp.config.json

4. 환경 변수

{
  "delegationMode": "ondemand",
  "allowedModels": ["qwen3.5:397b-cloud", "gemma4:31b-cloud"],
  "defaultModel": "qwen3.5:397b-cloud",
  "defaultPermissionMode": "auto",
  "baseUrl": "http://127.0.0.1:11434",
  "claudeBin": "claude",
  "stateDir": "~/.ollama-mcp/jobs",
  "jobTimeoutMs": 1800000,
  "maxInlineChars": 60000
}

설정 변경

설정은 모델이 아닌, 터미널에서 변경됩니다:

ollama-mcp-config                              # show current settings + active layers
ollama-mcp-config --mode auto                  # off | ondemand | auto
ollama-mcp-config --allow qwen3.5:397b-cloud   # or: --allow all
ollama-mcp-config --default-model qwen3.5:397b-cloud
ollama-mcp-config --permission-mode acceptEdits
ollama-mcp-config --scope project              # write ./ollama-mcp.config.json

그런 다음 Claude Code 세션을 다시 시작하세요 — 서버가 설정을 다시 읽습니다.

의도적으로 이에 대한 MCP 도구는 없습니다. 보안 모델을 참조하세요.

허용된 모델

allowedModels: [] (기본값)은 서버가 제공하는 모든 모델을 허용합니다. 비어 있지 않은 목록의 경우:

• delegate_start는 목록에 없는 모델을 거부하고, 자동으로 다른 모델을 대체하지 않고 허용된 집합을 명명합니다.

• ollama_models는 제외된 모델을 BLOCKED by allowedModels로 표시합니다.

• 허용 목록은 delegate_start 도구 설명에 포함되므로, 오케스트레이터는 추가 호출 없이 메뉴를 알 수 있습니다.

• CLI는 defaultModel을 새 목록 밖으로 이동시키는 변경을 거부합니다.

위임 모드

이는 오케스트레이터가 위임을 얼마나 적극적으로 사용하는지 제어하며, 모델이 실제로 읽는 도구 설명을 다시 작성합니다. 변경하려면 설계상 세션 재시작이 필요합니다.

auto 모드에서 설명은 오케스트레이터에게 독립적이고, 저렴하게 검증 가능하며, 맥락을 많이 필요로 하는 작업(대량 파일 요약, 첫 번째 검색, 기계적 리팩토링, 보일러플레이트 및 테스트 스캐폴딩, 로그 또는 diff 분류)을 위임하도록 지시하면서, 아키텍처 결정, 보안에 민감한 변경, 모호한 요구 사항 및 최종 검토는 스스로 유지하도록 합니다. 또한 위임된 주장을 확인하도록 지시받습니다. 그 이유는 운영에 있습니다.

도구 참조

delegate_start

delegate_followup는 job_id 또는 session_id와 동일한 prompt/prompt_file 쌍 및 선택적 permission_mode, max_turns, wait_seconds를 사용합니다.

운영

기본적으로 비동기

delegate_start는 밀리초 단위로 job_id를 반환합니다. 위임자는 백그라운드에서 계속 실행됩니다. 이렇게 하면 긴 작업이 세션을 지연시키거나 MCP 클라이언트 시간 초과를 유발하지 않습니다.

delegate_start({ prompt: "Audit src/ for unused exports" })
  → job_id A, session_id S, turn 1, state: running

delegate_status({ job_id: "A" })
  → recent activity:
      [tool] Grep: export
      [tool] Read: /repo/src/index.ts

delegate_result({ job_id: "A" })
  → the final text

이러한 함수 중 하나에 wait_seconds를 전달하면 대신 차단합니다 — 폴링 왕복이 가치 없는 짧은 작업에 유용합니다.

양방향 대화

모든 작업에는 session_id가 있습니다. delegate_followup에 job_id를 전달하면 전체 기록과 함께 세션이 재개됩니다. 각 턴이 새로운 job_id를 얻는 동안 session_id는 턴 전체에서 안정적으로 유지됩니다.

delegate_start({ prompt: "Summarise the auth flow in this repo" })
  → job A, session S, turn 1
delegate_followup({ job_id: "A", prompt: "Now list every place it can fail" })
  → job B, session S, turn 2   (delegate still remembers turn 1)

위임자가 관련 컨텍스트를 이미 로드한 경우 처음부터 다시 시작하는 것보다 후속 작업이 훨씬 저렴합니다.

긴 프롬프트

모든 프롬프트 매개변수에는 prompt_file 대응 값이 있습니다. 내부적으로 프롬프트는 항상 디스크에 기록된 후 stdin을 통해 CLI로 전달됩니다. argv 항목으로 전달되거나 셸을 통해 전달되지 않습니다. 백틱, $(...), 따옴표, 줄바꿈 및 글로브 문자는 그대로 전달되며, argv 길이 제한이 없습니다.

delegate_start({ prompt_file: "/tmp/refactor-brief.md" })

권한

위임은 기본적으로 defaultPermissionMode (auto)를 사용합니다. 특정 호출을 좁히려면:

// read-only review
delegate_start({ prompt: "...", disallowed_tools: ["Write", "Edit", "NotebookEdit"] })

// tightly scoped
delegate_start({ prompt: "...", allowed_tools: ["Read", "Grep", "Glob"] })

위임된 출력 신뢰하기

모든 완료된 결과는 도구 호출 횟수를 보고합니다. 약한 모델은 때때로 아무것도 실행하지 않고도 자신 있게 응답합니다. 개발 중에 한 모델은 Bash를 호출하지 않고 환경 변수가 설정되지 않았다고 주장했습니다. 강제로 실행하자 명령을 실행하고 올바른 값을 보고했습니다.

tool calls: 0을 포함하는 결과는 따라서 확인되지 않은 것으로 주석 처리됩니다:

tool calls: 0   <- answered without using any tools; treat factual claims as unverified

delegate_status는 실제 추적을 보여줍니다. 순전히 대화형 후속 질문은 합법적으로 0을 가질 수 있습니다. 이 플래그는 "이것을 뒷받침하는 것이 없다"는 의미이지 "무언가 고장났다"는 의미가 아닙니다.

취소

delegate_cancel({ job_id: "A" })

위임자 및 그 위임자가 시작한 모든 것을 종료하므로, 긴 빌드 도중에 있던 위임자가 빌드를 계속 실행하지 않도록 합니다.

작업 아티팩트

각 작업은 ~/.ollama-mcp/jobs/<job_id>/에 기록됩니다:

maxInlineChars보다 긴 결과는 도구 응답에서 잘리며 전체 텍스트는 result.txt에서 읽습니다. 자동으로 정리되지 않습니다. 원할 때마다 디렉토리를 삭제하십시오.

문제 해결

Cannot reach Ollama at http://127.0.0.1:11434 Ollama가 실행 중이 아닙니다. ollama serve를 시작하거나 데스크톱 앱을 엽니다. 다른 위치에서 수신 대기 중이면 OLLAMA_MCP_BASE_URL을 설정하십시오.

No models available from Ollama ollama pull qwen3.5:397b-cloud, 그리고 :cloud 모델의 경우 ollama signin을 실행하십시오.

<model> was retired at … (HTTP 410) Ollama가 해당 클라우드 모델을 제거했습니다. ollama list에는 여전히 로컬에 캐시된 매니페스트가 표시될 수 있습니다. 실제로 작동하는 모델을 확인하고 defaultModel을 업데이트하십시오.

Model "x" is not in the allowed list 의도된 대로 작동합니다. ollama-mcp-config --allow <models>를 실행한 후 다시 시작하십시오.

Claude Code에 도구가 표시되지 않음 도구 목록은 세션 시작 시 읽힙니다. 다시 시작하거나 claude mcp list를 확인하십시오.

위임자가 시작 오류와 함께 즉시 실패함 CLI를 찾을 수 없습니다. OLLAMA_MCP_CLAUDE_BIN을 claude의 절대 경로로 설정하십시오.

모든 것이 느림 클라우드 모델은 턴당 왕복 시간을 지불하며, Claude Code는 모든 요청에 큰 시스템 프롬프트(약 25k 토큰)를 전송합니다. max_turns를 사용하여 에이전트 루프를 제한하고 allowed_tools를 사용하여 위임자가 필요 이상으로 탐색하지 못하게 하십시오.

플랫폼 지원

플랫폼 차이는 src/platform.ts에 격리되어 있습니다:

바이너리 해상도. POSIX에서는 spawn이 PATH를 검색합니다. Windows에서는 네이티브 설치 시 claude.exe가 제공되고 npm 설치 시 claude.cmd가 제공되며, CreateProcess가 직접 실행할 수 없습니다. 따라서 서버는 PATH × PATHEXT를 검색하여 .exe를 선호하고, .cmd 셸을 cmd.exe를 통해 라우팅하는 방식으로 대체합니다.

인수 이스케이프. 이 대체 방법은 두 개의 레이어를 적용합니다: MSVCRT argv 인용, 그 다음 cmd 자체 메타 문자(& | < > ^ " ( ) % !)에 대한 캐럿 이스케이프. 두 번째 레이어를 건너뛰는 것이 고전적인 .cmd 명령어 주입 취약점입니다. 프롬프트는 이 경로를 절대 거치지 않습니다. stdin을 통해 전송됩니다. 한 가지 제한 사항: 여러 줄의 append_system_prompt는 cmd.exe 명령줄을 넘을 수 없으므로, 서버는 조용히 망가뜨리는 대신 OLLAMA_MCP_CLAUDE_BIN을 가리키는 명확한 오류를 발생시킵니다.

환경 허용 목록. Windows는 POSIX보다 훨씬 더 큰 집합을 유지합니다. SystemRoot와 windir은 선택 사항이 아닙니다. 이를 제거하면 Winsock이 초기화에 실패하여 자식이 localhost에도 소켓을 열 수 없습니다. 이름은 대소문자를 구분하지 않고 일치시키지만 부모의 원래 철자를 사용하여 복사합니다.

취소. POSIX 자식은 프로세스 그룹 리더로서 detached로 생성되고 process.kill(-pid)로 취소됩니다. Windows는 taskkill /T /F를 사용합니다. 어느 쪽이든 위임자의 하위 프로세스는 함께 종료됩니다. 서버는 종료될 때 실행 중인 위임자도 종료합니다.

보안 모델

자격 증명 격리가 핵심입니다. 자식 환경은 상속되지 않고 처음부터 구성되며, 공급자 변수는 Ollama 값이 적용되기 전에 제거됩니다. 이는 test/env-unit.mjs에서 다루어지며, test/e2e.mjs는 부모에 가짜 ANTHROPIC_API_KEY를 주입하고 위임자에게 도달하지 않는지 확인합니다.

위임 정책은 모델이 쓸 수 없습니다. delegationMode 또는 allowedModels를 변경하는 MCP 도구는 없습니다. 이전 버전에는 있었지만 실수였습니다: ondemand가 불편한 모델이 한 번의 호출로 auto로 전환한 다음 자유롭게 위임할 수 있었습니다. 설정은 이제 시작 시 한 번 로드되며, 런타임에 절대 변경되지 않으며, 도구 설명에는 정책이 모델이 변경할 수 있는 것이 아님을 명시합니다.

이것은 가드레일이지 보안 경계가 아닙니다. 셸 액세스 권한이 있는 에이전트는 여전히 구성 파일을 편집할 수 있습니다. 도구를 제거함으로써 얻는 이점은 그러한 변경이 작업 중간에 한 번의 조용한 도구 호출이 아니라 다음 재시작 시에만 적용되는 눈에 보이는 파일 편집이 된다는 점입니다. 완전히 차단하려면 MCP 등록 시 --env를 통해 값을 고정하십시오. 이는 구성 파일을 재정의합니다:

claude mcp add ollama --scope user \
  --env OLLAMA_MCP_DELEGATION_MODE=ondemand \
  --env OLLAMA_MCP_ALLOWED_MODELS=qwen3.5:397b-cloud \
  -- node /path/to/claude-ollama-delegate-mcp/dist/index.js

위임자는 파일 시스템을 상속받습니다. 사용자로 실행되며, 사용자가 지정한 cwd에서 defaultPermissionMode를 사용합니다. 위임된 세션은 다른 Claude Code 세션과 동일하게 취급하십시오. 덜 신뢰하는 모델에 작업을 맡길 때는 disallowed_tools 또는 읽기 전용 권한 모드를 사용하십시오.

개발

npm install        # installs and builds
npm run build      # tsc
npm run dev        # tsc --watch

테스트

node test/env-unit.mjs       # env isolation: no secret leaks, platform vars present
node test/quoting.mjs        # Windows argv/cmd escaping, incl. an injection probe
node test/killtree-unit.mjs  # process-tree termination
node test/e2e.mjs            # full MCP round trip           (needs Ollama running)
node test/async.mjs          # async polling, prompt_file, cancel  (needs Ollama)
CFG_PATH=/tmp/c.json CFG_CWD=/tmp node test/readonly.mjs   # config is read-only to the model

npm test는 네트워크가 필요 없는 세 가지 테스트를 실행합니다.

릴리스 게시

npm login                       # interactive, once per machine
npm version patch               # or minor / major -- tags and bumps
npm publish                     # prepare script builds first
git push --follow-tags

패키지는 claude-ollama-delegate-mcp이며 dist/, README.md 및 LICENSE만 포함합니다. publishConfig.access는 public이고, prepare는 패킹 전에 tsc를 실행하므로 오래된 dist/가 게시될 수 없습니다. 배송 전에 npm pack --dry-run으로 타르볼을 미리 보십시오.

레이아웃

라이선스

MIT — LICENSE 참조.