Ollama MCP 서버

ollama-MCP-server

Ollama와 통신하는 Model Context Protocol (MCP) 서버

개요

이 MCP 서버는 로컬 Olama LLM 인스턴스와 MCP 호환 애플리케이션 간의 원활한 통합을 가능하게 하여 고급 작업 분해, 평가 및 워크플로우 관리를 제공합니다.

주요 기능:

복잡한 문제의 작업 분해
결과 평가 및 검증
Ollama 모델 관리 및 실행
MCP 프로토콜을 통한 표준화된 통신
고급 오류 처리 및 자세한 오류 메시지
성능 최적화(연결 풀링, LRU 캐시)

구성요소

자원

서버는 다음 리소스를 구현합니다.

task:// - 개별 작업에 액세스하기 위한 URI 체계
result:// - 평가 결과에 액세스하기 위한 URI 체계
model:// - 사용 가능한 Olama 모델에 액세스하기 위한 URI 체계

각 리소스에는 최적의 LLM과의 상호 작용을 위한 적절한 메타데이터 및 MIME 유형이 설정되어 있습니다.

프롬프트와 도구 간의 관계

MCP 서버에서 프롬프트와 도구는 밀접하게 관련되어 있지만 다른 역할을 가지고 있습니다.

프롬프트 : LLM에 특정 사고 방법과 구조를 제공하는 스키마(Schema)와 같은 역할
도구 : 실제로 액션을 수행하는 핸들러(Handler)와 같은 역할

각 툴에는 대응하는 스키마(프롬프트)가 필요하므로 LLM의 사고 능력과 실제 시스템 기능을 효과적으로 연계시킬 수 있습니다.

프롬프트

서버는 몇 가지 특수 프롬프트를 제공합니다.

decompose-task - 복잡한 작업을 관리하기 쉬운 하위 작업으로 분해
- 작업 설명 및 입도 수준 옵션 매개변수 얻기
- 종속성과 추정 복잡성을 포함한 구조화된 분석을 반환합니다.
evaluate -result - 지정된 기준 에 대한 태스크 결과 분석
- 결과 내용 및 평가 매개변수 얻기
- 점수 및 개선 제안을 포함한 자세한 평가를 반환합니다.

도구

서버는 몇 가지 강력한 도구를 구현합니다.

add-task
- 필수 매개 변수: name (문자열), description (문자열)
- 선택적 매개 변수: priority (숫자), deadline (문자열), tags (배열)
- 시스템에 새 태스크를 작성하고 식별자를 리턴합니다.
- 해당 스키마: 작업 생성을 위한 데이터 검증 스키마
decompose-task
- 필수 매개 변수: task_id (문자열), granularity (문자열: "high"|"medium"|"low")
- 선택적 매개변수: max_subtasks (숫자)
- Ollama를 사용하여 복잡한 작업을 관리 가능한 하위 작업으로 분해
- 해당 스키마: 위의 decompose-task 프롬프트
evaluate-result
- 필수 매개 변수: result_id (문자열), criteria (객체)
- 선택적 매개 변수: detailed (부울)
- 지정된 기준에 대한 결과를 평가하고 피드백 제공
- 해당 스키마: 위의 evaluate-result 프롬프트
run-model
- 필수 매개 변수: model (문자열), prompt (문자열)
- 선택적 매개 변수: temperature (숫자), max_tokens (숫자)
- 지정된 파라미터로 Olama 모델 실행
- 해당 스키마: Ollama 모델 실행 매개변수 검증 스키마

새로운 기능과 개선점

확장 오류 처리

서버는 보다 상세하고 구조화된 오류 메시지를 제공합니다. 이렇게 하면 클라이언트 응용 프로그램이 오류를 보다 효과적으로 처리할 수 있습니다. 오류 응답의 예:

{
  "error": {
    "message": "Task not found: task-123",
    "status_code": 404,
    "details": {
      "provided_id": "task-123"
    }
  }
}

성능 최적화

연결 풀링 : 공유 HTTP 연결 풀을 사용하면 요청 성능이 향상되고 리소스 사용률이 줄어듭니다.
LRU 캐시 : 동일하거나 유사한 요청에 대한 응답을 캐시하면 응답 시간이 단축되고 Olama 서버의 부하가 줄어듭니다.

이러한 설정은 config.py 에서 조정할 수 있습니다.

# パフォーマンス関連設定
cache_size: int = 100                 # キャッシュに保存する最大エントリ数
max_connections: int = 10             # 同時接続の最大数
max_connections_per_host: int = 10    # ホストごとの最大接続数
request_timeout: int = 60             # リクエストタイムアウト（秒）

모델 지정 기능

개요

Ollama-MCP-Server는 여러 가지 방법으로 Olamama 모델을 지정할 수 있는 유연한 기능을 제공합니다.

모델 지정 우선 순위

모델은 다음 우선순위로 지정됩니다.

툴 호출시의 파라미터 ( model 파라미터)
MCP 구성 파일의 env 섹션
환경 변수 ( OLLAMA_DEFAULT_MODEL )
기본값 ( llama3 )

MCP 설정 파일을 사용한 모델 지정

Claude Desktop과 같은 클라이언트에서 사용하는 경우 MCP 구성 파일을 사용하여 모델을 지정할 수 있습니다.

{
  "mcpServers": {
    "ollama-MCP-server": {
      "command": "python",
      "args": [
        "-m",
        "ollama_mcp_server"
      ],
      "env": [
        {"model": "llama3:latest"}
      ]
    }
  }
}

사용 가능한 모델 확인

서버가 시작될 때 구성된 모델이 있는지 확인합니다. 모델을 찾을 수 없으면 경고 로그가 출력됩니다. 또한 run-model 도구는 사용 가능한 모델 목록을 반환하므로 사용자는 유효한 모델을 선택할 수 있습니다.

오류 처리 개선

지정된 모델이 없거나 통신 오류가 발생하면 자세한 오류 메시지가 제공됩니다. 오류 메시지에는 사용 가능한 모델 목록이 포함되므로 사용자는 문제를 신속하게 해결할 수 있습니다.

테스트

프로젝트에는 포괄적 인 테스트 스위트가 포함되어 있습니다.

단위 테스트 : 개별 구성 요소의 기능 테스트
통합 테스트 : 엔드 투 엔드 워크플로우 테스트

테스트를 실행하려면 :

# すべてのテストを実行
python -m unittest discover

# 特定のテストを実行
python -m unittest tests.test_integration

설정

환경 변수

OLLAMA_HOST=http://localhost:11434
DEFAULT_MODEL=llama3
LOG_LEVEL=info

Ollama 설정

Ollama가 설치되고 적절한 모델로 실행 중인지 확인하십시오.

# Ollamaをインストール（まだインストールされていない場合）
curl -fsSL https://ollama.com/install.sh | sh

# 推奨モデルをダウンロード
ollama pull llama3
ollama pull mistral
ollama pull qwen2

빠른 시작

설치

pip install ollama-mcp-server

Claude Desktop 설정

MacOS

경로: ~/Library/Application\ Support/Claude/claude_desktop_config.json

Windows

경로: %APPDATA%/Claude/claude_desktop_config.json

"mcpServers": {
  "ollama-MCP-server": {
    "command": "uv",
    "args": [
      "--directory",
      "/path/to/ollama-MCP-server",
      "run",
      "ollama-MCP-server"
    ],
    "ENV":["model":"deepseek:r14B"]
  }
}

"mcpServers": {
  "ollama-MCP-server": {
    "command": "uvx",
    "args": [
      "ollama-MCP-server"
    ]
  }
}

사용 예

작업 분해

복잡한 작업을 관리 가능한 하위 작업으로 분해하려면 :

result = await mcp.use_mcp_tool({
    "server_name": "ollama-MCP-server",
    "tool_name": "decompose-task",
    "arguments": {
        "task_id": "task://123",
        "granularity": "medium",
        "max_subtasks": 5
    }
})

결과 평가

특정 기준에 대한 결과를 평가하려면 :

evaluation = await mcp.use_mcp_tool({
    "server_name": "ollama-MCP-server",
    "tool_name": "evaluate-result",
    "arguments": {
        "result_id": "result://456",
        "criteria": {
            "accuracy": 0.4,
            "completeness": 0.3,
            "clarity": 0.3
        },
        "detailed": true
    }
})

Ollama 모델 실행

Ollama 모델에 대해 직접 쿼리를 실행하려면 :

response = await mcp.use_mcp_tool({
    "server_name": "ollama-MCP-server",
    "tool_name": "run-model",
    "arguments": {
        "model": "llama3",
        "prompt": "量子コンピューティングを簡単な言葉で説明してください",
        "temperature": 0.7
    }
})

개발

프로젝트 설정

리포지토리 복제:

git clone https://github.com/yourusername/ollama-MCP-server.git
cd ollama-MCP-server

가상 환경 만들기 및 활성화:

python -m venv venv
source venv/bin/activate  # Windowsの場合: venv\Scripts\activate

개발 종속성 설치:

uv sync --dev --all-extras

로컬 개발

프로젝트에는 유용한 개발 스크립트가 포함되어 있습니다.

서버 실행

./run_server.sh

옵션:

--debug : 디버그 모드에서 실행 (로그 레벨 : DEBUG)
--log=LEVEL : 로그 레벨 지정(DEBUG, INFO, WARNING, ERROR, CRITICAL)

테스트 실행

./run_tests.sh

옵션:

--unit : 단위 테스트만 실행
--integration : 통합 테스트만 실행
--all : 모든 테스트 실행(기본값)
--verbose : 상세한 테스트 출력

빌드 및 공개

패키지를 배포 용으로 준비하려면 :

종속성을 동기화하여 잠금 파일 업데이트:

uv sync

패키지 배포판 빌드:

uv build

이렇게하면 dist/ 디렉토리에 소스 및 휠 배포판이 생성됩니다.

PyPI에 게시:

uv publish

참고 : PyPI 자격 증명은 환경 변수 또는 명령 플래그로 설정해야합니다.

토큰: --token 또는 UV_PUBLISH_TOKEN
또는 사용자 이름/비밀번호: --username / UV_PUBLISH_USERNAME 및 --password / UV_PUBLISH_PASSWORD

디버깅

MCP 서버는 stdio를 통해 실행되므로 디버깅이 어려울 수 있습니다. 최적의 디버깅 경험을 위해 MCP Inspector 를 사용하는 것이 좋습니다.

npm 을 사용하여 MCP Inspector를 시작하려면 다음 명령을 실행합니다.

npx @modelcontextprotocol/inspector uv --directory /path/to/ollama-MCP-server run ollama-mcp-server

시작 시 Inspector는 브라우저에서 액세스하여 디버깅을 시작할 수 있는 URL을 표시합니다.

아키테

기여

공헌은 환영합니다! 언제든지 풀 요청을 제출하십시오.

리포지토리 포크
기능 브랜치 만들기 ( git checkout -b feature/amazing-feature )
변경 커밋 ( git commit -m 'Add some amazing feature' )
브랜치에 푸시 ( git push origin feature/amazing-feature )
끌어오기 요청 열기

라이센스

이 프로젝트는 MIT 라이센스하에 라이센스됩니다. 자세한 내용은 LICENSE 파일을 참조하십시오.

감사의 말

우수한 프로토콜 설계를 제공하는 Model Context Protocol 팀
로컬 LLM 실행에 액세스할 수 있는 Olama 프로젝트
이 프로젝트의 모든 기여자

This server cannot be installed

security - not tested

license - not found

quality - not tested

local-only server

The server can only run on the client's local machine because it depends on local resources.

A server that enables seamless integration between local Ollama LLM instances and MCP-compatible applications, providing advanced task decomposition, evaluation, and workflow management capabilities.

Related MCP Servers

MCP Ollama Server
emgeee
A
security
A
license
A
quality
MCP Ollama server integrates Ollama models with MCP clients, allowing users to list models, get detailed information, and interact with them through questions.
Last updated -
3
12
Python
MIT License
Ollama MCP Server
rawveg
-
security
A
license
-
quality
Enables seamless integration between Ollama's local LLM models and MCP-compatible applications, supporting model management and chat interactions.
Last updated -
165
47
TypeScript
AGPL 3.0
Ollama MCP Server
NightTrek
A
security
F
license
A
quality
A bridge that enables seamless integration of Ollama's local LLM capabilities into MCP-powered applications, allowing users to manage and run AI models locally with full API coverage.
Last updated -
10
33
JavaScript
MCP Base
jsmiff
-
security
F
license
-
quality
A generic Model Context Protocol framework for building AI-powered applications that provides standardized ways to create MCP servers and clients for integrating LLMs with support for Ollama and Supabase.
Last updated -
TypeScript

View all related MCP servers