Ollama-Omega MCP server

로컬 모델부터 클라우드 호스팅된 거대 모델까지, 전체 Ollama 생태계를 모든 MCP 호환 IDE로 연결하는 강화된 MCP 서버입니다. 래퍼 스크립트나 무거운 SDK는 없습니다. 단 두 개의 종속성만 사용하는 단일 Python 파일입니다.

설계 원칙: Ollama-Omega는 Ollama를 추상화하지 않습니다. 정보 손실 없이 6개의 검증되고 오류 처리가 완료된 MCP 도구를 통해 전체 Ollama API 인터페이스를 노출합니다.

아키텍처

┌─────────────────────────────────────────────────────┐
│                    MCP Client (IDE)                  │
│         Claude Desktop / Antigravity / etc.          │
└──────────────────────┬──────────────────────────────┘
                       │ stdio (JSON-RPC 2.0)
┌──────────────────────▼──────────────────────────────┐
│              ollama_mcp_server.py                     │
│  ┌──────────┐ ┌──────────┐ ┌───────────────────┐    │
│  │ Validator│ │ Dispatch │ │ Singleton httpx   │    │
│  │ + Schema │→│ Router   │→│ AsyncClient       │    │
│  └──────────┘ └──────────┘ │ (no redirects)    │    │
│                             └─────────┬─────────┘    │
└───────────────────────────────────────┼──────────────┘
                                        │ HTTP
┌───────────────────────────────────────▼──────────────┐
│                  Ollama Daemon                        │
│    Local models (GPU) │ Cloud models (API proxy)      │
└───────────────────────────────────────────────────────┘

도구 (6)

도구	목적
`ollama_health`	연결 상태 확인 및 현재 실행/로드된 모델 목록 확인
`ollama_list_models`	크기, 로드 상태, 수정 날짜를 포함한 모든 사용 가능한 모델 목록 확인
`ollama_chat`	메시지 기록 및 시스템 프롬프트를 포함한 채팅 완료 요청 전송
`ollama_generate`	채팅 기록 없이 주어진 프롬프트에 대한 응답 생성
`ollama_show_model`	특정 모델에 대한 상세 정보(라이선스, 매개변수) 표시
`ollama_pull_model`	Ollama 라이브러리에서 모델 다운로드

강화 감사

#	범주	완화 조치
1	SSRF	httpx 클라이언트에서 리다이렉트 비활성화 (`follow_redirects=False`)
2	리소스 누수	싱글톤 `AsyncClient` — 서버 수명 동안 하나의 연결 풀 사용
3	입력 검증	모든 HTTP 호출 전 각 도구에서 `_validate_required()` 게이트 적용
4	JSON 안전성	`_safe_json()` 래퍼 — 잘못된 형식의 응답에도 충돌 방지
5	구조화된 로깅	원시 `print()` 대신 `logging` 모듈을 통한 모든 stderr 출력
6	DRY 페이로드	`_build_options()`를 통한 온도/토큰 매핑 중앙화
7	오류 삭제	`_error()` 도우미 — 스택 추적이나 내부 정보가 클라이언트로 유출되지 않음

빠른 시작

요구 사항

Python 3.11+
pip install mcp httpx

Claude Desktop / Antigravity 설정

{
  "mcpServers": {
    "ollama": {
      "command": "uv",
      "args": [
        "--directory",
        "path/to/ollama-mcp",
        "run",
        "python",
        "ollama_mcp_server.py"
      ],
      "env": {
        "PYTHONUTF8": "1",
        "OLLAMA_HOST": "http://localhost:11434",
        "OLLAMA_TIMEOUT": "300"
      }
    }
  }
}

환경 변수

변수	기본값	설명
`OLLAMA_HOST`	`http://localhost:11434`	Ollama 데몬 URL
`OLLAMA_TIMEOUT`	`300`	요청 시간 제한(초) (대규모 모델 풀링/클라우드 추론을 위해 길게 설정)
`PYTHONUTF8`	—	Windows 유니코드 안전성을 위해 `1`로 설정

클라우드 모델

Ollama-Omega는 버전에 구애받지 않습니다. Ollama 데몬이 (API 프록시를 통해 qwen3.5:397b-cloud와 같은) 클라우드 호스팅 모델을 노출하는 경우, 구성 변경 없이 동일한 6개의 도구를 통해 액세스할 수 있습니다.

파일 구조

Ollama-Omega/
  ollama_mcp_server.py     # MCP server (~307 lines) — hardened, single-file
  pyproject.toml            # Package metadata, CLI entry, PyPI classifiers
  requirements.txt          # mcp>=1.0.0, httpx>=0.27.0
  glama.json                # Glama MCP directory registration
  LICENSE                   # MIT
  CHANGELOG.md              # Version history
  tests/
    test_server.py           # 48 tests — tools, dispatch, errors, SSRF, config
  examples/
    basic_usage.py           # Programmatic MCP client example
  docs/
    BUILD_SPEC.md            # Internal build specification

테스트

pip install pytest
python -m pytest tests/ -v

다음 사항을 포함한 48개의 테스트:

도구 정의 — 스키마 검증, 필수 필드, 설명
도우미 함수 — 옵션 빌더, 검증, JSON 안전성, 오류 형식 지정
디스패처 — 모의 HTTP 응답을 사용한 6개 도구 경로 전체
오류 처리 — 연결, 시간 제한, HTTP 상태, 예외 삭제
구성 — 환경 기본값, SSRF 완화, 서버 ID

동반 서버

Ollama-Omega는 Omega Brain MCP의 전송 계층입니다. 이는 세션 간 에피소드 기억과 10단계 VERITAS 빌드 파이프라인을 제공합니다. 이 둘은 결합하여 주권 지능 스택을 형성합니다.

라이선스

MIT

Ollama-Omega