mcp-ollama

API 기반 오케스트레이터의 비용을 절감하기 위해 로컬 Ollama 모델을 래핑하는 MCP 서버입니다.

로컬 모델로 작업을 전달하는 9가지 도구(텍스트 생성, 요약, 코드 작업, 기계적 변환, 커밋/PR/변경 로그 초안 작성)를 제공합니다. 오케스트레이터가 로컬로 라우팅할 대상을 결정하며, 이 서버는 라우팅을 수행합니다.

• 전송: stdio

• 런타임: Node 18+

• 기본 모델: hermes3:8b (OLLAMA_MODEL을 통해 재정의 가능)

• Ollama 호스트: http://localhost:11434 (OLLAMA_HOST를 통해 재정의 가능)

• 모델 가중치, 클라우드 호출, 텔레메트리를 포함하지 않습니다. 모든 요청은 Ollama가 실행 중인 호스트 내에서 유지됩니다.

• 라이선스: Apache-2.0

목적

토큰 단위로 비용이 청구되는 오케스트레이터(Claude Code, Cursor, Anthropic API, Cline, Aider)는 모든 분류, docstring, 커밋 메시지에 대해 비용을 지불합니다. 대부분의 작업은 최상위 모델이 필요하지 않습니다. 동일한 머신에서 Ollama로 라우팅하면 동일한 작업을 무료로 더 빠르게 수행할 수 있습니다. mcp-ollama는 그 라우팅 인터페이스입니다.

오케스트레이팅 모델이 무엇을 어디로 라우팅할지 결정합니다. 이 서버는 배관 역할을 하며, 작업 분류에 대해 복잡한 판단을 내리지 않습니다. 적절한 도구를 선택하고 텍스트를 전달하면 결과를 반환받습니다.

Related MCP server: ProjectBrain

설치

소스에서 설치

git clone https://github.com/true-alter/mcp-ollama.git
cd mcp-ollama
npm install
npm run build

또한 최소 하나 이상의 모델이 풀링된 실행 중인 Ollama 인스턴스가 필요합니다:

# Default — 8B, fast, good for classifications and short generations
ollama pull hermes3:8b

# Optional — code-specialised, heavier, better for local_code tasks
ollama pull qwen2.5-coder:32b

Docker

docker build -t mcp-ollama .
docker run -i --rm \
  -e OLLAMA_HOST=http://host.docker.internal:11434 \
  -e OLLAMA_MODEL=hermes3:8b \
  mcp-ollama

제공된 Dockerfile은 host.docker.internal:11434를 가리키므로 컨테이너가 호스트의 Ollama에 도달할 수 있습니다.

실행 (stdio)

node dist/index.js

Stdio 서버는 MCP 클라이언트(Claude Code, Cursor 등)에 의해 실행됩니다. 직접 실행하는 것은 디버깅 용도로만 유용합니다.

Claude Code 설정

claude mcp add --transport stdio ollama -- node /absolute/path/to/mcp-ollama/dist/index.js

또는 ~/.claude/settings.json 파일:

{
  "mcpServers": {
    "ollama": {
      "transport": "stdio",
      "command": "node",
      "args": ["/absolute/path/to/mcp-ollama/dist/index.js"],
      "env": {
        "OLLAMA_HOST": "http://localhost:11434",
        "OLLAMA_MODEL": "hermes3:8b"
      }
    }
  }
}

도구

전체 도구 스키마는 MCP 인트로스펙션을 통해 노출되며, MCP를 지원하는 모든 클라이언트는 이를 자동으로 열거합니다.

환경 변수

모든 도구 호출은 model을 명시적으로 재정의할 수 있습니다. 환경 변수 기본값은 설정되지 않은 경우에만 적용됩니다. local_code는 호출 시마다 코드 특화 모델을 전달하는 것이 더 효과적이며, local_summarize와 local_draft는 기본 모델로도 충분합니다.

모델 선택 가이드

호스트에서 무엇을 사용할 수 있는지 확실하지 않은 경우 세션 시작 시 local_models를 사용하세요.

문제 해결

도구 호출 시 Ollama error 404 발생. 모델이 풀링되지 않았습니다. ollama pull <name>을 실행하거나 클라이언트에서 local_pull을 호출하세요.

fetch failed / 연결 거부. Ollama가 실행 중이지 않거나 OLLAMA_HOST가 잘못된 곳을 가리키고 있습니다. curl $OLLAMA_HOST/api/tags로 확인하세요. 컨테이너 내부에서 localhost는 컨테이너 자체를 의미하므로, macOS/Windows에서는 host.docker.internal을 사용하거나 Linux에서는 브리지 IP를 사용하세요.

도구 호출이 느림. 콜드 모델에 대한 첫 번째 호출은 로드 시간이 발생합니다. 동일한 Ollama 프로세스 내에서의 후속 호출은 훨씬 빠릅니다. 모델이 사용 가능한 VRAM보다 크면 Ollama는 CPU로 대체됩니다. ollama ps를 확인하여 확인하세요.

출력이 비어 있거나 잘림. max_tokens는 도구당 기본값이 2048입니다. 긴 생성이 필요한 경우 도구 호출 시 max_tokens를 명시적으로 전달하세요.

보안 정책

mcp-ollama는 구성된 OLLAMA_HOST 외에 자체적인 네트워크 호출을 수행하지 않습니다. 텔레메트리, 분석, 자동 업데이트 핑거를 포함하지 않습니다. 도구 입력은 Ollama의 HTTP API로 그대로 전달되고 응답이 다시 전달됩니다. 서버 자체는 호출 간 상태를 유지하지 않습니다.

Ollama를 localhost(기본값)에서 실행하면 전체 루프가 호스트 내에 유지됩니다. OLLAMA_HOST를 원격 엔드포인트로 지정하는 경우, 해당 엔드포인트의 보안 정책을 신뢰할 수 있는 것으로 간주하십시오. 오타로 인해 프롬프트가 제3자 호스트로 전송될 가능성이 있습니다.

보안 문제를 보고하려면 SECURITY.md를 참조하세요.

기여

버그 리포트와 작은 패치는 환영합니다. CONTRIBUTING.md를 참조하세요. 더 큰 설계 변경은 시간을 투자하기 전에 먼저 이슈를 열어 범위에 대해 논의해 주시기 바랍니다.

ALTER의 일부

mcp-ollama는 AI 경제를 위한 신원 인프라의 일부로서 ALTER에 의해 유지 관리됩니다. ALTER 신원 MCP 서버는 mcp.truealter.com에서 호스팅됩니다. TypeScript 클라이언트는 @truealter/sdk를 참조하세요.

라이선스

Apache License 2.0. 전체 텍스트는 LICENSE를 참조하세요. Copyright 2026 Alter Meridian Pty Ltd (ABN 54 696 662 049).