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 (선택 사항): 필터링 옵션이 포함된 객체
동작 (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
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