Ollama MCP Bridge
Um serviço de API de ponte conectando Ollama com servidores Model Context Protocol (MCP).
Documentação
Fornece uma camada de API na frente da API do Ollama, adicionando perfeitamente ferramentas de vários servidores MCP para que cada requisição do Ollama possa acessar todas as ferramentas conectadas de forma transparente.
Ollama MCP Bridge
Sumário
- Recursos
- Requisitos
- Instalação
- Como Funciona
- Configuração
- Uso
- Desenvolvimento
- Contribuindo
- Projetos Relacionados
- Inspiração e Créditos
Recursos
- 🚀 Servidores Pré-carregados: Todos os servidores MCP são conectados na inicialização a partir da configuração JSON
- 📝 Configuração JSON: Configure vários servidores com comandos e ambientes complexos
- 🌐 Múltiplos Tipos de Transporte: Conecte-se a servidores MCP via stdio (processos locais), HTTP (StreamableHTTP) ou SSE
- 🎯 Filtragem de Ferramentas: Filtre ferramentas por servidor com modos de inclusão/exclusão para controle detalhado
- 🧩 Expansão de Variáveis de Configuração: Suporta
${env:VAR_NAME}e${workspaceFolder}em strings de configuração - 🔗 Integração de Ferramentas: Processamento automático de chamadas de ferramentas e integração de respostas
- 🔄 Execução de Ferramentas em Múltiplas Rodadas: Percorre automaticamente várias rodadas de chamadas de ferramentas até a conclusão
- 🛡️ Limites de Ferramentas Configuráveis: Defina o número máximo de rodadas de execução de ferramentas para evitar chamadas excessivas
- 🛠️ Todas as Ferramentas Disponíveis: O Ollama pode usar qualquer ferramenta de qualquer servidor conectado simultaneamente
- 🔌 Compatibilidade Completa com a API:
/api/chatadiciona ferramentas enquanto todos os outros endpoints da API do Ollama são proxy de forma transparente - 🔧 Ollama Configurável: Especifique uma URL personalizada do servidor Ollama via CLI (suporta modelos locais e na nuvem)
- 🔐 Cabeçalhos Upstream Opcionais: Envie cabeçalhos personalizados fixos (ex.: uma chave de API) com cada requisição ao servidor upstream
- ☁️ Suporte a Modelos na Nuvem: Funciona com modelos de nuvem do Ollama
- 🔄 Verificação de Versão: Verificação automática de versões mais recentes com instruções de atualização
- 🌊 Respostas em Streaming: Suporta streaming incremental de respostas para os clientes
- 🤔 Modo de Raciocínio: Faz proxy de mensagens intermediárias de "pensamento" do Ollama e das ferramentas MCP
- ⚡️ Backend FastAPI: API assíncrona moderna com documentação automática
- 🏗️ Arquitetura Modular: Separação limpa em módulos de CLI, API e gerenciamento de MCP
- 💻 CLI Typer: Interface de linha de comando limpa com opções configuráveis
- 📊 Registro Estruturado: Usa loguru para registro abrangente
- 📦 Pacote PyPI: Facilmente instalável via pip ou uv a partir do PyPI
- 🗣️ Configuração do Prompt do Sistema: Permite definir um prompt de sistema para o comportamento do assistente
- 🐳 Imagens Docker Multi-Arquitetura ✨ NOVO: Imagens
linux/amd64elinux/arm64pré-construídas publicadas no GitHub Container Registry a cada lançamento
Requisitos
- Python >= 3.10.15
- Servidor Ollama em execução (local ou remoto)
- Arquivo de configuração do servidor MCP com pelo menos um servidor MCP definido (veja o exemplo abaixo)
Instalação
Você pode instalar o ollama-mcp-bridge de várias maneiras, dependendo da sua preferência:
Início Rápido
Instale instantaneamente com uvx:
uvx ollama-mcp-bridge
Ou, instale do PyPI com pip
pip install --upgrade ollama-mcp-bridge
Ou, execute com Docker Compose
docker compose up
Isso usa o arquivo docker-compose.yml incluído, que:
- Compila a ponte a partir do código-fonte usando o Dockerfile
- Conecta-se ao Ollama em execução na máquina host (
host.docker.internal:11434) - Mapeia o arquivo de configuração de ./mcp-config.json (inclui um servidor meteorológico simulado para demonstração)
- Expõe a porta
8000no host - Permite todas as origens CORS (configurável via variável de ambiente
CORS_ORIGINS) - Suporta timeouts de requisição do Ollama configuráveis via
OLLAMA_PROXY_TIMEOUT
[!TIP] Para pular a compilação local e usar a imagem pré-construída do GitHub Container Registry, substitua o bloco
build:emdocker-compose.ymlpor:image: ghcr.io/jonigl/ollama-mcp-bridge:latest
Ou, execute apenas com Docker
[!NOTE] ✨ NOVO: Imagens Docker multi-arquitetura pré-construídas (
linux/amd64elinux/arm64) agora são publicadas automaticamente no GitHub Container Registry a cada lançamento. Nenhuma compilação local é necessária!
Imagens multi-arquitetura pré-construídas (linux/amd64 e linux/arm64) são publicadas no GitHub Container Registry a cada lançamento. Tags disponíveis:
latest— lançamento estável mais recentevX.Y.Z— versão específica (ex.:v0.10.0)sha-<commit>— build de commit SHA exato
docker run -p 8000:8000 \
-e OLLAMA_URL=http://host.docker.internal:11434 \
-v "$PWD/mcp-config.json:/mcp-config.json" \
-v "$PWD/mock-weather-mcp-server:/mock-weather-mcp-server" \
-w / \
ghcr.io/jonigl/ollama-mcp-bridge:latest
Principais flags:
-p 8000:8000— expõe a ponte no seu host na porta8000-e OLLAMA_URL=http://host.docker.internal:11434— roteia o tráfego do Ollama para a máquina host (necessário no macOS e Windows; no Linux use--network hostou o IP do host)-v "$PWD/mcp-config.json:/mcp-config.json"— monta sua configuração local no contêiner-v "$PWD/mock-weather-mcp-server:/mock-weather-mcp-server"— monta o servidor MCP simulado sem:ropara queuvpossa criar seu.venvdentro do diretório-w /— define o diretório de trabalho como/para que caminhos relativos emmcp-config.jsonsejam resolvidos corretamente
[!NOTE] No Linux,
host.docker.internalpode não ser resolvido automaticamente. Use--network hoste mantenhaOLLAMA_URL=http://localhost:11434, ou substitua-o pelo IP da LAN do seu host.
Ou, instale a partir do código-fonte
# Clone the repository
git clone https://github.com/jonigl/ollama-mcp-bridge.git
cd ollama-mcp-bridge
# Start Ollama (if not already running)
ollama serve
# Run the bridge
uv run ollama-mcp-bridge
Se você quiser instalar o projeto em modo editável (para desenvolvimento):
# Install the project in editable mode
uv tool install --editable .
# Run it like this:
ollama-mcp-bridge
Como Funciona
- Inicialização: Todos os servidores MCP definidos na configuração são carregados e conectados
- Verificação de Versão: Na inicialização, a ponte verifica se há versões mais recentes e notifica se uma atualização estiver disponível
- Coleta de Ferramentas: As ferramentas de todos os servidores são coletadas e disponibilizadas ao Ollama
- Requisição de Conclusão de Chat (somente endpoint
/api/chat): Quando uma requisição de conclusão de chat é recebida em/api/chat:- A requisição é encaminhada ao Ollama (local ou nuvem) junto com a lista de todas as ferramentas disponíveis
- Se o Ollama escolher invocar alguma ferramenta, essas chamadas são executadas através dos servidores MCP correspondentes
- As respostas das ferramentas são enviadas de volta ao Ollama
- O processo se repete em um loop até que não sejam necessárias mais chamadas de ferramentas
- As respostas são transmitidas em streaming para o cliente em tempo real durante todo o processo
- A resposta final (com todos os resultados das ferramentas integrados) é retornada ao cliente
- Este é o único endpoint onde as ferramentas dos servidores MCP são integradas.
- Outros Endpoints: Todos os outros endpoints (exceto
/api/chat,/healthe/version) são totalmente proxy para o servidor Ollama subjacente, sem modificação. - Registro: Todas as operações são registradas usando loguru para depuração e monitoramento
Configuração
Configuração dos Servidores MCP
Você pode configurar servidores MCP de três maneiras:
- Processo local (stdio):
{"command": "...", "args": [...], "env": {...}} - Endpoint remoto (StreamableHTTP):
{"url": "https://..."}- Usa StreamableHTTP por padrão - Endpoint remoto (SSE):
{"url": "https://.../sse"}- Se a URL terminar com/sse, a ponte se conecta via Server-Sent Events
Crie um arquivo de configuração MCP em mcp-config.json com seus servidores:
{
"mcpServers": {
"weather": {
"command": "uv",
"args": [
"--directory",
"./mock-weather-mcp-server",
"run",
"main.py"
],
"env": {
"MCP_LOG_LEVEL": "ERROR"
},
"toolFilter": {
"mode": "include",
"tools": ["get_current_temperature", "get_forecast"]
}
},
"remote_streamable_http": {
"url": "https://example.com/mcp"
},
"remote_sse": {
"url": "https://example.com/sse"
},
"filesystem": {
"command": "npx",
"args": [
"-y",
"@modelcontextprotocol/server-filesystem",
"/tmp"
],
"toolFilter": {
"mode": "exclude",
"tools": ["delete_file", "write_file"]
}
}
}
}
Filtragem de Ferramentas
Você pode filtrar quais ferramentas de um servidor MCP são disponibilizadas ao Ollama usando a configuração opcional toolFilter:
toolFilter(opcional): Objeto com opções de filtragemmode:"include"(lista de permissão) ou"exclude"(lista de negação). O padrão é"include"se não for especificado.tools: Matriz de nomes exatos de ferramentas para incluir ou excluir
Comportamento:
- Se
toolFilternão estiver definido ou a matriztoolsestiver vazia, todas as ferramentas do servidor são carregadas (comportamento padrão) - Modo de inclusão (lista de permissão): Somente as ferramentas listadas na matriz
toolssão disponibilizadas. Se uma ferramenta listada não for encontrada no servidor, um aviso é registrado, mas a conexão com o servidor continua. - Modo de exclusão (lista de negação): Todas as ferramentas, exceto as listadas na matriz
tools, são disponibilizadas. As ferramentas listadas são filtradas. - Os nomes das ferramentas devem corresponder exatamente (sensível a maiúsculas/minúsculas)
- Valores inválidos de
modefazem o aplicativo sair com uma mensagem de erro
Exemplo com modo de inclusão (padrão):
{
"mcpServers": {
"weather": {
"command": "uv",
"args": ["--directory", "./mock-weather-mcp-server", "run", "main.py"],
"toolFilter": {
"tools": ["get_current_temperature", "get_forecast"]
}
}
}
}
Exemplo com modos explícitos:
{
"mcpServers": {
"weather": {
"command": "uv",
"args": ["--directory", "./mock-weather-mcp-server", "run", "main.py"],
"toolFilter": {
"mode": "include",
"tools": ["get_current_temperature"]
}
},
"filesystem": {
"command": "npx",
"args": ["-y", "@modelcontextprotocol/server-filesystem", "/tmp"],
"toolFilter": {
"mode": "exclude",
"tools": ["delete_file", "write_file"]
}
}
}
}
Expansão de Variáveis
A configuração também suporta expansão simples em qualquer valor de string:
${workspaceFolder}resolve para o diretório que contém o arquivo de configuração${env:VAR_NAME}resolve para a variável de ambiente correspondente
Exemplo:
{
"mcpServers": {
"filesystem": {
"command": "npx",
"args": [
"-y",
"@modelcontextprotocol/server-filesystem",
"${workspaceFolder}/data"
]
},
"remote_with_headers": {
"url": "https://example.com/mcp",
"headers": {
"X-Client-Name": "ollama-mcp-bridge",
"X-Request-Tag": "${env:MCP_REQUEST_TAG}"
}
}
}
}
[!WARNING] Limitações de Comandos Docker: Ao executar no Docker, os servidores MCP devem usar comandos disponíveis no contêiner:
- ✅
npxpara servidores MCP baseados em Node.js- ✅
uvxpara servidores MCP baseados em Python- ✅ Executáveis diretos no contêiner
- ❌ Comandos
docker(a menos que Docker-in-Docker esteja configurado)- ❌ Caminhos de arquivos locais da sua máquina host
Configuração de CORS
Configure o Compartilhamento de Recursos entre Origens (CORS) para permitir requisições dos seus aplicativos frontend:
# Allow all origins (default, not recommended for production)
ollama-mcp-bridge
# Allow specific origins
CORS_ORIGINS="http://localhost:3000,https://myapp.com" ollama-mcp-bridge
# Allow multiple origins with different ports
CORS_ORIGINS="http://localhost:3000,http://localhost:8080,https://app.example.com" ollama-mcp-bridge
Registro de CORS:
- A ponte registra a configuração de CORS na inicialização
- Mostra um aviso ao usar
*(todas as origens) - Mostra as origens permitidas quando configurado corretamente
[!WARNING] Usar
CORS_ORIGINS="*"permite todas as origens e não é recomendado para produção. Sempre especifique origens exatas por segurança.
Variáveis de Ambiente
CORS_ORIGINS: Lista separada por vírgulas de origens permitidas (padrão:*)*permite todas as origens (exibe aviso nos logs)- Exemplo:
CORS_ORIGINS="http://localhost:3000,https://myapp.com" ollama-mcp-bridge
MAX_TOOL_ROUNDS: Número máximo de rodadas de execução de ferramentas (padrão: ilimitado)- Pode ser substituído pelo parâmetro de CLI
--max-tool-rounds(a CLI tem precedência) - Exemplo:
MAX_TOOL_ROUNDS=5 ollama-mcp-bridge
- Pode ser substituído pelo parâmetro de CLI
OLLAMA_URL: URL do servidor Ollama (padrão:http://localhost:11434)- Pode ser substituído pelo parâmetro de CLI
--ollama-url - Útil para implantações Docker e gerenciamento de configuração
- Exemplo:
OLLAMA_URL=http://192.168.1.100:11434 ollama-mcp-bridge
- Pode ser substituído pelo parâmetro de CLI
UPSTREAM_HEADERS: Objeto JSON opcional de cabeçalhos a enviar ao servidor upstream (ex.: para autenticação por chave de API)- Esses cabeçalhos não são consumidos pelo próprio Ollama, mas por qualquer coisa que fique entre a ponte e o Ollama (proxy reverso / gateway / camada de autenticação) — o upstream
- Pode ser estendido/substituído por cabeçalho com o parâmetro de CLI repetível
--upstream-header(a CLI tem precedência) - Útil para implantações Docker onde os cabeçalhos não devem aparecer na lista de processos
- Exemplo:
UPSTREAM_HEADERS='{"Authorization": "Bearer token123", "X-API-Key": "secret"}' ollama-mcp-bridge
OLLAMA_PROXY_TIMEOUT: Tempo limite para requisições HTTP enviadas ao Ollama, em milissegundos (padrão: não definido)- Quando não definido, a ponte mantém o comportamento existente (algumas requisições usam padrões de biblioteca;
/api/chatnão tem tempo limite) - Quando definido para um valor > 0, o tempo limite é aplicado às requisições HTTP destinadas ao Ollama
- Quando definido para 0, os tempos limite são desabilitados para requisições HTTP do Ollama (a ponte registra um aviso)
- Respostas de chat em streaming sempre usam sem tempo limite, mesmo quando essa variável está definida
- Exemplo (10 minutos):
OLLAMA_PROXY_TIMEOUT=600000 ollama-mcp-bridge
- Quando não definido, a ponte mantém o comportamento existente (algumas requisições usam padrões de biblioteca;
SYSTEM_PROMPT: Prompt de sistema opcional a ser prefixado em todas as requisições/api/chatencaminhadas- Pode ser definido via variável de ambiente
SYSTEM_PROMPTou flag de CLI--system-prompt - Se fornecido, a ponte prefixará uma mensagem de sistema (papel:
system) ao início do arraymessagespara requisições/api/chat, a menos que a requisição já comece com uma mensagem de sistema. - Exemplo:
SYSTEM_PROMPT="You are a concise assistant." ollama-mcp-bridge
- Pode ser definido via variável de ambiente
Uso
[!NOTE] Um script de exemplo de servidor MCP é fornecido em mock-weather-mcp-server/main.py.
Iniciar o Servidor
# Start with default settings (config: ./mcp-config.json, host: 0.0.0.0, port: 8000)
ollama-mcp-bridge
# Start with custom configuration file
ollama-mcp-bridge --config /path/to/custom-config.json
# Custom host and port
ollama-mcp-bridge --host 0.0.0.0 --port 8080
# Custom Ollama server URL (local or cloud)
ollama-mcp-bridge --ollama-url http://192.168.1.100:11434
# Send custom header(s) to the upstream server (repeatable, curl-style "Name: Value")
ollama-mcp-bridge --upstream-header "X-API-Key: your-key"
ollama-mcp-bridge --upstream-header "Authorization: Bearer xxx" --upstream-header "X-API-Key: yyy"
# Keep the secret out of your shell history by letting the shell expand an env var
ollama-mcp-bridge --upstream-header "Authorization: Bearer $MY_API_KEY"
# Limit tool execution rounds (prevents excessive tool calls)
ollama-mcp-bridge --max-tool-rounds 5
# Set a system prompt to prepend to all /api/chat requests
ollama-mcp-bridge --system-prompt "You are a concise assistant."
# Combine options
ollama-mcp-bridge --config custom.json --host 0.0.0.0 --port 8080 --ollama-url http://remote-ollama:11434 --max-tool-rounds 10
# Combine options with an upstream API key header
ollama-mcp-bridge --config custom.json --ollama-url http://remote-ollama:11434 --upstream-header "X-API-Key: your-key" --port 8080
# Check version and available updates
ollama-mcp-bridge --version
[!TIP] Se você usa
uvxpara executar a ponte, especifique o comando comouvx ollama-mcp-bridgeem vez de apenasollama-mcp-bridge.
[!NOTE] Esta ponte suporta tanto respostas em streaming quanto modo de pensamento. Você recebe respostas incrementais conforme são geradas, com chamadas de ferramentas e mensagens intermediárias de pensamento automaticamente proxy entre o Ollama e todas as ferramentas MCP conectadas.
Opções de CLI
--config: Caminho para o arquivo de configuração MCP (padrão:mcp-config.json)--host: Host para vincular o servidor (padrão:0.0.0.0)--port: Porta para vincular o servidor (padrão:8000)--ollama-url: URL do servidor Ollama (padrão:http://localhost:11434)--upstream-header: Cabeçalho a enviar ao servidor upstream como"Name: Value"(repetível; também pode ser definido via variável de ambienteUPSTREAM_HEADERS)--max-tool-rounds: Número máximo de rodadas de execução de ferramentas (padrão: ilimitado)--reload: Ativa recarga automática durante o desenvolvimento--version: Mostra informações de versão, verifica atualizações e sai--system-prompt: Prompt de sistema opcional a prefixar em requisições/api/chat(padrão: nenhum)
Quando configurados, os cabeçalhos personalizados do upstream são adicionados às verificações de saúde da ponte e a todas as requisições que a ponte envia ao servidor upstream, incluindo /api/chat e endpoints do Ollama proxy de forma transparente.
Uso da API
A API está disponível em http://localhost:8000.
- Documentação Swagger UI: http://localhost:8000/docs
- Endpoints compatíveis com Ollama:
POST /api/chat— Endpoint de chat (igual à API do Ollama, mas com suporte a ferramentas MCP)- Este é o único endpoint onde as ferramentas do servidor MCP são integradas. Todas as chamadas de ferramentas são tratadas e as respostas são mescladas de forma transparente para o cliente.
- Todos os outros endpoints (exceto
/api/chat,/healthe/version) são totalmente proxy para o servidor Ollama subjacente sem nenhuma modificação. Você pode usar seus clientes e bibliotecas Ollama existentes normalmente.
- Endpoints específicos da ponte:
GET /health— Endpoint de verificação de saúde (não proxy)GET /version— Informações de versão e verificação de atualizações
[!IMPORTANT]
/api/chaté o único endpoint com integração de ferramentas MCP. Todos os outros endpoints são proxy transparente para o Ollama./healthe/versionsão específicos da ponte.
Esta ponte atua como um proxy drop-in para a API do Ollama, mas com todas as ferramentas MCP de todos os servidores conectados disponíveis para cada requisição /api/chat. A ponte automaticamente trata várias rodadas de execução de ferramentas até a conclusão, transmitindo respostas em tempo real. Você pode usar seus clientes e bibliotecas Ollama existentes com modelos Ollama locais e em nuvem, basta apontá-los para esta ponte em vez do seu servidor Ollama.
Exemplo: Chat
curl -N -X POST http://localhost:8000/api/chat \
-H "accept: application/json" \
-H "Content-Type: application/json" \
-d '{
"model": "qwen3:0.6b",
"messages": [
{
"role": "system",
"content": "You are a weather assistant."
},
{
"role": "user",
"content": "What is the weather like in Paris today?"
}
],
"think": true,
"stream": true,
"options": {
"temperature": 0.7,
"top_p": 0.9
}
}'
[!TIP] Use
/docspara exploração e testes interativos da API.
Desenvolvimento
Dependências Principais
- FastAPI: Framework web moderno para a API
- Typer: Framework de CLI para interface de linha de comando
- loguru: Registro estruturado em todo o aplicativo
- ollama: Cliente Python para comunicação com Ollama
- mcp: Biblioteca de cliente do Model Context Protocol
- pytest: Framework de testes para validação da API
Testes
O projeto tem dois tipos de testes:
Testes Unitários (compatíveis com GitHub Actions)
# Install test dependencies
uv sync --extra test
# Run unit tests (no server required)
uv run pytest tests/test_unit.py -v
Esses testes verificam:
- Carregamento de arquivo de configuração
- Importações de módulos e inicialização
- Estrutura do projeto
- Formatos de definição de ferramentas
Testes de Integração (requerem serviços em execução)
# First, start the server in one terminal
ollama-mcp-bridge
# Then in another terminal, run the integration tests
uv run pytest tests/test_api.py -v
Esses testes verificam:
- Endpoints da API com requisições HTTP reais
- Funcionalidade de ponta a ponta com Ollama
- Chamada de ferramentas e integração de resposta
Testes Manuais
# Quick manual test with curl (server must be running)
curl -X GET "http://localhost:8000/health"
# Check version information and update status
curl -X GET "http://localhost:8000/version"
curl -X POST "http://localhost:8000/api/chat" \
-H "Content-Type: application/json" \
-d '{"model": "qwen3:0.6b", "messages": [{"role": "user", "content": "What tools are available?"}]}'
[!NOTE] Os testes exigem que o servidor esteja em execução em localhost:8000. Certifique-se de iniciar o servidor antes de executar o pytest.
Contribuindo
Aceitamos contribuições! Por favor, consulte CONTRIBUTING.md para:
- Instruções de configuração de desenvolvimento
- Diretrizes de formatação de código (Black)
- Procedimentos de teste
- Convenções de commit
Projetos Relacionados
-
Cliente MCP para Ollama - Um cliente de interface de usuário baseada em texto (TUI) para interagir com servidores MCP usando Ollama. Recursos incluem suporte a múltiplos servidores, troca dinâmica de modelos, respostas em streaming, gerenciamento de ferramentas, capacidades human-in-the-loop, modo de pensamento, configuração completa de parâmetros de modelo, prompt de sistema personalizado e preferências salvas. Construído para desenvolvedores que trabalham com LLMs locais.
-
simple-ollama-chat – Um cliente de bate-papo simples e amigável para Ollama que funciona perfeitamente com o Ollama MCP Bridge. Permite interagir com modelos e usar todas as ferramentas do servidor MCP integradas por meio da ponte, com uma interface limpa e configuração fácil. Ideal para testar rapidamente, conversar e explorar LLMs aumentados por ferramentas através da ponte.
Inspiração e Créditos
Este projeto é baseado no cliente MCP básico do meu artigo na Medium: Construa um Cliente MCP em Minutos: Agentes de IA Locais Ficaram Reais.
A inspiração para criar esta ponte simples veio deste problema no GitHub: jonigl/mcp-client-for-ollama#22, sugerido por @nyomen.
Feito com ❤️ por jonigl