GitHub - rawveg/ollama-mcp: An MCP Server for Ollama

rawveg/ollama-mcp 프로젝트는 로컬 LLM(Large Language Model) 접근성을 강화하여 AI 어시스턴트를 슈퍼차지하는 것을 목표로 하는 MCP (Model Context Protocol) 서버이다. 이 서버는 Ollama SDK의 모든 기능을 MCP tool로 노출함으로써, Claude Desktop 및 Cline과 같은 MCP 호환 애플리케이션과의 원활한 통합을 가능하게 한다.

핵심 방법론 및 아키텍처:

이 프로젝트의 핵심은 MCP 서버로서, MCP 클라이언트의 요청을 받아 Ollama SDK 호출로 변환하는 중개자 역할을 수행한다. 서버의 아키텍처는 Hot-Swap Architecture, 즉 autoloader 패턴을 채택한다. 이는 src/tools/ 디렉토리에 새로운 tool 파일을 추가하기만 하면 서버 재시작 없이도 자동으로 tool이 발견되고 로드되는 방식이다. 각 tool은 독립적인 TypeScript 모듈로, toolDefinition 객체를 export한다. 이 toolDefinition은 tool의 name, description, inputSchema, 그리고 비동기 handler 함수를 정의한다. inputSchema는 Zod를 사용하여 정의된 Type-Safe 스키마로, tool 인자의 유효성을 엄격하게 검증하여 robustness를 확보한다.

이러한 모듈화된 접근 방식은 새로운 tool의 추가 및 테스트를 용이하게 하며, 100% function coverage 및 96%+ overall test coverage를 달성하는 데 기여한다. 서버는 ollama 객체 (Ollama 클라이언트 인스턴스), tool 인자 (args), 응답 형식 (format)을 handler 함수에 전달하여 tool의 기능을 구현한다.

주요 기능:

* Ollama Cloud Support: https://ollama.com을 통해 Ollama의 클라우드 플랫폼과 완전히 통합된다.
* 14 Comprehensive Tools: Ollama SDK의 광범위한 기능에 대한 접근을 제공한다. 이는 ollama_list, ollama_show, ollama_pull, ollama_push, ollama_copy, ollama_delete, ollama_create와 같은 모델 관리 tool과, ollama_ps, ollama_generate, ollama_chat, ollama_embed와 같은 모델 운영 tool을 포함한다.
* Web Tools (Ollama Cloud): OLLAMA_API_KEY를 필요로 하는 ollama_web_search 및 ollama_web_fetch를 통해 실시간 웹 검색 및 콘텐츠 추출 기능을 제공한다.
* Hybrid Mode: 로컬 Ollama 인스턴스와 Ollama Cloud 모델 및 웹 tool을 하나의 서버에서 동시에 사용할 수 있도록 구성할 수 있다. 이는 OLLAMA_HOST를 로컬 주소로 설정하고 OLLAMA_API_KEY를 제공하는 방식으로 이루어진다.
* Zero Dependencies: 최소한의 footprint와 최대의 성능을 위해 외부 의존성을 최소화했다.
* Drop-in Integration: Claude Desktop, Cline 등 MCP 클라이언트와의 쉬운 통합을 지원한다.

Ollama Skill과의 관계:

이 MCP 서버는 Ollama 모델과 상호작용하기 위한 tool을 제공하지만, Ollama Skill (Skillsforge Marketplace에서 사용 가능)은 이러한 tool을 효과적으로 사용하는 방법에 대한 지식(expertise)을 제공한다. MCP 서버가 "자동차"라면, Ollama Skill은 "운전 강습"에 비유된다. Ollama Skill은 모델 선택 및 구성, 최적의 프롬프트 전략, chat vs generate, embeddings 등 다양한 tool의 사용 시기, 성능 최적화, tool calling 및 function support와 같은 고급 기능에 대한 지침을 제공한다.

설치 및 구성:

* Claude Desktop/Cline 설치: 해당 애플리케이션의 설정 파일(claude_desktop_config.json 또는 cline_mcp_settings.json)에 mcpServers 객체를 추가하여 command로 npx -y ollama-mcp를 지정하는 방식으로 쉽게 통합할 수 있다.
* 환경 변수: OLLAMA_HOST (기본값: http://127.0.0.1:11434) 및 OLLAMA_API_KEY 환경 변수를 통해 Ollama 서버 엔드포인트 및 Ollama Cloud API 키를 구성할 수 있다.

재시도(Retry) 동작:

MCP 서버는 Ollama API와의 통신 중 발생하는 일시적인 실패를 처리하기 위한 지능적인 재시도 로직을 포함한다. ollama_web_search 및 ollama_web_fetch와 같은 웹 tool에 대해 특히 구현되어 있다.

* 자동 재시도 전략:
* HTTP 429 (Too Many Requests)와 같은 rate limit 오류 시 자동으로 재시도한다.
* 최대 3회 재시도 (총 4회 요청, 초기 요청 포함).
* 각 요청의 timeout은 30초로 설정되어 hung connections를 방지한다.
* API가 제공하는 Retry-After 헤더를 존중하며, 이는 지연 시간(Delay-Seconds 또는 HTTP-Date 형식)을 정확히 따르거나 계산한다.
* Retry-After 헤더가 없거나 유효하지 않은 경우 exponential backoff with jitter 전략을 사용한다.
* 초기 지연: 1초 (기본)
* 최대 지연: 10초 (기본)
* 지연 시간 계산: $\text{random}(0, \min(\text{initialDelay} \times 2^\text{attempt}, \text{maxDelay}))$
* 오류 처리:
* 재시도 대상 오류 (transient failures): HTTP 429, 500, 502, 503, 504 등 일시적인 서버 또는 게이트웨이 오류.
* 비재시도 대상 오류 (permanent failures): Request timeouts, Network timeouts, Abort/cancel errors, HTTP 4xx (429 제외), 기타 HTTP 5xx (500, 502, 503, 504 제외) 등 영구적이거나 클라이언트 측 오류.

이러한 재시도 메커니즘은 API 문제에 대한 견고한 처리를 보장하며, 서버가 제공하는 재시도 지침을 존중하고 과도한 요청 속도를 방지한다.

사용 예시:

MCP 클라이언트는 JSON 형식으로 tool을 호출한다.
* Chat with a Model:

json{
      "tool": "ollama_chat",
      "arguments": {
        "model": "llama3.2:latest",
        "messages": [
          { "role": "user", "content": "Explain quantum computing" }
        ]
      }
    }

* Generate Embeddings:

json{
      "tool": "ollama_embed",
      "arguments": {
        "model": "nomic-embed-text",
        "input": ["Hello world", "Embeddings are great"]
      }
    }

* Web Search:

json{
      "tool": "ollama_web_search",
      "arguments": {
        "query": "latest AI developments",
        "max_results": 5
      }
    }

이 프로젝트는 AGPL-3.0 라이선스 하에 배포되며, Node.js, npm, Ollama SDK, MCP SDK, Zod를 사용하여 개발되었다.

GitHub - rawveg/ollama-mcp: An MCP Server for Ollama

요약

상세 내용