Ollama API를 위한 MCP 서버 도구 통합 브리지

Ollama API 앞에 API 레이어를 제공하여, 여러 MCP 서버의 도구들을 원활하게 추가함으로써 모든 Ollama 요청이 연결된 모든 도구에 투명하게 접근할 수 있도록 합니다.

• 기능 (Features)

• 요구 사항 (Requirements)

• 설치 (Installation)

• 작동 원리 (How It Works)

• 설정 (Configuration)

• 사용법 (Usage)

• 개발 (Development)

• 기여하기 (Contributing)

• 관련 프로젝트 (Related Projects)

• 영감 및 크레딧 (Inspiration and Credits)

• 🚀
  사전 로드된 서버 (Pre-loaded Servers): 모든 MCP 서버는 시작 시 JSON 설정으로부터 연결됩니다 - 📝
  JSON 설정 (JSON Configuration): 복잡한 명령 및 환경을 가진 여러 서버를 구성할 수 있습니다 - 🌐
  다양한 전송 유형 (Multiple Transport Types): stdio (로컬 프로세스), HTTP (StreamableHTTP), 또는 SSE를 통해 MCP 서버에 연결합니다 - 🎯
  도구 필터링 (Tool Filtering): 세밀한 제어를 위해 포함/제외 (include/exclude) 모드로 서버별 도구를 필터링합니다 - 🧩
  설정 변수 확장 (Config Variable Expansion): 설정 문자열 내에서 ${env:VAR_NAME} 및 ${workspaceFolder}를 지원합니다 - 🔗
  도구 통합 (Tool Integration): 자동 도구 호출 (tool call) 처리 및 응답 통합 - 🔄
  다회차 도구 실행 (Multi-Round Tool Execution): 완료될 때까지 여러 회차의 도구 호출을 자동으로 반복합니다 - 🛡️
  설정 가능한 도구 제한 (Configurable Tool Limits): 과도한 도구 호출을 방지하기 위해 최대 도구 실행 회차를 설정합니다 - 🛠️
  모든 도구 사용 가능 (All Tools Available): Ollama는 연결된 모든 서버의 어떤 도구든 동시에 사용할 수 있습니다 - 🔌
  완전한 API 호환성 (Complete API Compatibility): /api/chat

도구를 추가하면서도 다른 모든 Ollama API 엔드포인트는 투명하게 프록시(Proxy)됩니다 - 🔧
설정 가능한 Ollama (Configurable Ollama): CLI를 통해 사용자 정의 Ollama 서버 URL을 지정할 수 있습니다 (로컬 및 클라우드 모델 지원) - ☁️
클라우드 모델 지원 (Cloud Model Support): Ollama 클라우드 모델과 함께 작동합니다 - 🔄
버전 확인 (Version Check): 업그레이드 안내와 함께 최신 버전 여부를 자동으로 확인합니다 - 🌊
스트리밍 응답 (Streaming Responses): 클라이언트로의 점진적인 응답 스트리밍을 지원합니다 - 🤔
사고 모드 (Thinking Mode): Ollama 및 MCP 도구로부터 오는 중간

로컬 빌드 (local build)를 건너뛰고 대신 GitHub Container Registry의 사전 빌드된 이미지를 사용하려면, docker-compose.yml 파일의 build: 블록을 다음과 같이 교체하세요:

image: ghcr.io/jonigl/ollama-mcp-bridge:latest

참고

✨ 새로운 기능 (NEW): 이제 매 릴리스(release)마다 사전 빌드된 멀티 아키텍처 (multi-arch) Docker 이미지 (linux/amd64 및 linux/arm64)가 GitHub Container Registry에 자동으로 게시됩니다. 로컬 빌드가 필요하지 않습니다!

매 릴리스마다 사전 빌드된 멀티 아키텍처 이미지 (linux/amd64 및 linux/arm64)가 GitHub Container Registry에 게시됩니다. 사용 가능한 태그(tags)는 다음과 같습니다:

latest — 가장 최근의 안정적인 릴리스 (stable release)
vX.Y.Z — 특정 버전 (예: v0.10.0)
sha-<commit> — 정확한 커밋 SHA 빌드

docker run -p 8000:8000 \
-e OLLAMA_URL=http://host.docker.internal:11434 \
-v "$PWD/mcp-config.json:/mcp-config.json" \
...

주요 플래그 (Key flags):

-p 8000:8000 — 호스트의 8000 포트로 브리지 (bridge)를 노출합니다.
-e OLLAMA_URL=http://host.docker.internal:11434 — Ollama 트래픽을 호스트 머신으로 라우팅합니다 (macOS 및 Windows에서 필수이며, Linux에서는 대신 --network host 또는 호스트의 IP를 사용하세요).
-v "$PWD/mcp-config.json:/mcp-config.json" — 로컬 설정 파일을 컨테이너 내부로 마운트 (mount)합니다.
-v "$PWD/mock-weather-mcp-server:/mock-weather-mcp-server" — :ro 없이 모의 (mock) MCP 서버를 마운트하여 uv가 디렉토리 내부에 .venv를 생성할 수 있도록 합니다.
-w / — 작업 디렉토리 (working directory)를 /로 설정하여 mcp-config.json의 상대 경로가 올바르게 해석되도록 합니다.

참고

Linux에서는 host.docker.internal이 자동으로 해석되지 않을 수 있습니다. --network host를 사용하고 OLLAMA_URL=http://localhost:11434를 유지하거나, 호스트의 LAN IP로 교체하여 사용하세요.

# 저장소 클론 (Clone the repository)
git clone https://github.com/jonigl/ollama-mcp-bridge.git
cd ollama-mcp-bridge
...

프로젝트를 편집 가능 모드 (editable mode, 개발용)로 설치하려면 다음과 같이 하세요:

# 프로젝트를 편집 가능 모드로 설치
uv tool install --editable .
# 다음과 같이 실행합니다:
...

시작 (Startup): 설정에 정의된 모든 MCP 서버가 로드되고 연결됩니다.
버전 확인 (Version Check): 시작 시 브리지는 최신 버전을 확인하며, 업데이트가 가능한 경우 알림을 보냅니다.
도구 수집 (Tool Collection): 모든 서버의 도구(Tools)가 수집되어 Ollama에서 사용할 수 있게 됩니다.
채팅 완성 요청 (Chat Completion Request) (/api/chat 엔드포인트 전용):

• /api/chat으로 채팅 완성 요청이 수신되면:
  • 요청이 사용 가능한 모든 도구 목록과 함께 Ollama(로컬 또는 클라우드)로 전달됩니다.
  • Ollama가 도구 호출을 선택하면, 해당 도구 호출은 대응하는 MCP 서버를 통해 실행됩니다.
  • 도구 응답은 다시 Ollama로 전달됩니다.
  • 더 이상의 도구 호출이 필요하지 않을 때까지 이 프로세스는 루프(Loop) 내에서 반복됩니다.
  • 전체 프로세스 동안 응답은 클라이언트로 실시간 스트리밍(Stream)됩니다.
  • 최종 응답(모든 도구 결과가 통합된 상태)이 클라이언트로 반환됩니다.
    이곳은 MCP 서버 도구가 통합되는 유일한 엔드포인트입니다.

기타 엔드포인트 (Other Endpoints): /api/chat, /health, /version을 제외한 모든 기타 엔드포인트는 수정 없이 하위 Ollama 서버로 완전히 프록시(Proxy)됩니다.
로깅 (Logging): 모든 작업은 디버깅 및 모니터링을 위해 loguru를 사용하여 로그로 기록됩니다.

MCP 서버는 세 가지 방식으로 구성할 수 있습니다:

로컬 프로세스 (stdio): {"command": "...", "args": [...], "env": {...}}

원격 엔드포인트 (StreamableHTTP): {"url": "https://..."}

• 기본적으로 StreamableHTTP를 사용합니다.

원격 엔드포인트 (SSE): {"url": "https://.../sse"}

• URL이 /sse로 끝나면, 브리지는 서버 전송 이벤트 (Server-Sent Events, SSE)를 통해 연결합니다.

mcp-config.json 파일에 서버 정보를 포함하여 MCP 설정 파일을 생성하세요:

{
"mcpServers": {
"weather": {
...

선택 사항인 toolFilter 설정을 사용하여 MCP 서버의 도구 중 어떤 것을 Ollama에서 사용할 수 있게 할지 필터링할 수 있습니다:

toolFilter (선택 사항): 필터링 옵션이 포함된 객체

• mode (선택 사항): `

동작 (Behavior):

• toolFilter가 설정되지 않았거나 tools 배열이 비어 있는 경우, 서버의 모든 도구가 로드됩니다 (기본 동작)
• Include mode (허용 목록/allow-list): tools 배열에 나열된 도구만 사용할 수 있게 됩니다. 나열된 도구가 서버에서 발견되지 않으면 경고가 기록되지만 서버 연결은 계속됩니다.
• Exclude mode (차단 목록/deny-list): tools 배열에 나열된 도구를 제외한 모든 도구가 사용할 수 있게 됩니다. 나열된 도구들은 필터링되어 제외됩니다.
  • 도구 이름은 정확히 일치해야 합니다 (대소문자 구분)
  • 잘못된 mode 값은 애플리케이션을 에러 메시지와 함께 종료시킵니다.

Include mode 사용 예시 (기본값):

{
"mcpServers": {
"weather": {
...

명시적 모드 사용 예시:

{
"mcpServers": {
"weather": {
...

설정 파일은 모든 문자열 값에서 다음과 같은 간단한 확장을 지원합니다:

${workspaceFolder}: 설정 파일이 포함된 디렉토리로 해석됩니다.
${env:VAR_NAME}: 해당하는 환경 변수로 해석됩니다.

예시:

{
"mcpServers": {
"filesystem": {
...

⚠️ 경고

Docker 명령어 제한 사항: Docker에서 실행할 때, MCP 서버는 컨테이너 내에서 사용 가능한 명령어를 사용해야 합니다:

• ✅ Node.js 기반 MCP 서버의 경우 npx 사용
• ✅ Python 기반 MCP 서버의 경우 uvx 사용
• ✅ 컨테이너 내의 직접 실행 파일 사용
• ❌ docker 명령어 (Docker-in-Docker가 구성되지 않은 경우)
• ❌ 호스트 머신의 로컬 파일 경로

프론트엔드 애플리케이션의 요청을 허용하려면 교차 출처 리소스 공유 (CORS)를 구성하십시오:

# 모든 출처 허용 (기본값, 프로덕션 환경에서는 권장되지 않음)
ollama-mcp-bridge
# 특정 출처 허용
...

CORS 로깅:

• 브리지는 시작 시 CORS 설정을 기록합니다.
• * (모든 출처)를 사용하는 경우 경고를 표시합니다.
• 올바르게 구성된 경우 허용된 출처를 표시합니다.

⚠️ 경고

CORS_ORIGINS="*"를 사용하는 것은 모든 출처를 허용하므로 프로덕션 환경에서는 권장되지 않습니다. 보안을 위해 항상 정확한 출처를 지정하십시오.

CORS_ORIGINS: 허용된 출처의 쉼표로 구분된 목록 (기본값: *)

모든 출처를 허용합니다 (로그에 경고 표시) - 예시:
CORS_ORIGINS="http://localhost:3000,https://myapp.com" ollama-mcp-bridge

MAX_TOOL_ROUNDS

: 도구 실행 (tool execution) 라운드의 최대 횟수 (기본값: 무제한) - --max-tool-rounds CLI 파라미터로 재정의할 수 있습니다 (CLI가 우선순위를 가집니다) - 예시:
MAX_TOOL_ROUNDS=5 ollama-mcp-bridge

OLLAMA_URL

: Ollama 서버의 URL (기본값: http://localhost:11434) - --ollama-url CLI 파라미터로 재정의할 수 있습니다. Docker 배포 및 구성 관리 시 유용합니다. - 예시:
OLLAMA_URL=http://192.168.1.100:11434 ollama-mcp-bridge

OLLAMA_PROXY_TIMEOUT

: Ollama로 전송되는 HTTP 요청에 대한 타임아웃(timeout) 설정이며 단위는 밀리초 (milliseconds) 입니다 (기본값: 설정되지 않음) - 설정되지 않은 경우, 브릿지는 기존 동작을 유지합니다 (일부 요청은 라이브러리 기본값을 사용하며, /api/chat은 타임아웃이 적용되지 않습니다) - 0보다 큰 값으로 설정하면, Ollama로 향하는 HTTP 요청에 타임아웃이 적용됩니다 - 0으로 설정하면, Ollama HTTP 요청에 대한 타임아웃이 비활성화됩니다 (브릿지에 경고가 기록됩니다) - 스트리밍 채팅 응답 (Streaming chat responses)은 이 변수가 설정되어 있더라도 항상 타임아웃을 사용하지 않습니다. - 예시 (10분):
OLLAMA_PROXY_TIMEOUT=600000 ollama-mcp-bridge

SYSTEM_PROMPT

: 모든 전달된 /api/chat 요청의 앞에 추가할 선택 사항인 시스템 프롬프트 (system prompt) - SYSTEM_PROMPT 환경 변수 또는 --system-prompt CLI 플래그를 통해 설정할 수 있습니다. - 프롬프트가 제공되면, 요청이 이미 시스템 메시지로 시작하지 않는 한 브릿지는 /api/chat 요청의 messages 배열 시작 부분에 시스템 메시지 (role: system)를 추가합니다. - 예시:
SYSTEM_PROMPT="You are a concise assistant." ollama-mcp-bridge

# 기본 설정으로 시작 (config: ./mcp-config.json, host: 0.0.0.0, port: 8000)
ollama-mcp-bridge

# 사용자 정의 구성 파일로 시작
...

Tip

uvx를 사용하여 브릿지를 실행하는 경우, 단순히 ollama-mcp-bridge라고 입력하는 대신 uvx ollama-mcp-bridge와 같이 명령어를 지정해야 합니다.

Note

이 브리지(bridge)는 스트리밍 응답(streaming responses)과 사고 모드(thinking mode)를 모두 지원합니다. 응답이 생성되는 대로 점진적인 응답을 받을 수 있으며, 도구 호출(tool calls)과 중간 사고 메시지(intermediate thinking messages)가 Ollama와 모든 연결된 MCP 도구 간에 자동으로 프록시(proxy)됩니다.

--config
: MCP 설정 파일 경로 (기본값: mcp-config.json)

--host
: 서버를 바인딩할 호스트 (기본값: 0.0.0.0)

--port
: 서버를 바인딩할 포트 (기본값: 8000)

--ollama-url
: Ollama 서버 URL (기본값: http://localhost:11434)

--max-tool-rounds
: 최대 도구 실행 라운드 (기본값: 무제한)

--reload
: 개발 중 자동 재로드(auto-reload) 활성화

--version
: 버전 정보 표시, 업데이트 확인 후 종료

--system-prompt
: /api/chat 요청 앞에 추가할 선택적 시스템 프롬프트 (기본값: 없음)

API는 http://localhost:8000에서 사용할 수 있습니다.

Swagger UI 문서: http://localhost:8000/docs

Ollama 호환 엔드포인트(endpoints):
POST /api/chat
— 채팅 엔드포인트 (Ollama API와 동일하지만 MCP 도구 지원 포함)
이곳은 MCP 서버 도구가 통합되는 유일한 엔드포인트입니다.
모든 도구 호출은 처리되며, 클라이언트를 위해 응답이 투명하게 병합됩니다.

그 외 모든 엔드포인트 (/api/chat, /health, /version 제외)는 수정 없이 기반이 되는 Ollama 서버로 완전히 프록시(proxy)됩니다. 기존의 Ollama 클라이언트와 라이브러리를 평소와 같이 사용할 수 있습니다.

브리지 전용 엔드포인트:
GET /health