ollama-mcp-bridge 0.3.0

Bridge API service connecting Ollama with Model Context Protocol (MCP) servers

Provides an API layer in front of the Ollama API, seamlessly adding tools from multiple MCP servers so every Ollama request can access all connected tools transparently.

Ollama MCP Bridge

Features

• 🏗️ Modular Architecture: Clean separation into CLI, API, and MCP management modules
• 🚀 Pre-loaded Servers: All MCP servers are connected at startup from JSON configuration
• 🛠️ All Tools Available: Ollama can use any tool from any connected server simultaneously
• 🔄 Complete API Compatibility: /api/chat adds tools while all other Ollama API endpoints are transparently proxied
• ⚡️ FastAPI Backend: Modern async API with automatic documentation
• 💻 Typer CLI: Clean command-line interface with configurable options
• 📊 Structured Logging: Uses loguru for comprehensive logging
• 🔧 Configurable Ollama: Specify custom Ollama server URL via CLI
• 🔗 Tool Integration: Automatic tool call processing and response integration
• 📝 JSON Configuration: Configure multiple servers with complex commands and environments
• 🌊 Streaming Responses: Supports incremental streaming of responses to clients
• 🤔 Thinking Mode: Proxies intermediate "thinking" messages from Ollama and MCP tools

Requirements

• Python >= 3.10.15
• Ollama server running (local or remote)
• MCP server scripts configured in mcp-servers-config/mcp-config.json

Installation

# Clone the repository
git clone https://github.com/jonigl/ollama-mcp-bridge.git
cd ollama-mcp-bridge

# Install dependencies using uv
uv sync

# Start Ollama (if not already running)
ollama serve

# Run the bridge (preferred)
ollama-mcp-bridge

If you want to install the project in editable mode (for development):

# Install the project in editable mode
uv tool install --editable .
# Run it like this:
ollama-mcp-bridge

How It Works

1. Startup: All MCP servers defined in the configuration are loaded and connected
2. Tool Collection: Tools from all servers are collected and made available to Ollama
3. Chat Completion Request: When a chat completion request is received:

• The request is forwarded to Ollama along with the list of all available tools
• If Ollama chooses to invoke any tools, those tool calls are executed through the corresponding MCP servers
• Tool responses are fed back to Ollama
• The final response (with tool results integrated) is returned to the client

4. Logging: All operations are logged using loguru for debugging and monitoring

Configuration

Create an MCP configuration file at mcp-servers-config/mcp-config.json with your servers:

{
  "mcpServers": {
    "weather": {
      "command": "uv",
      "args": [
        "--directory",
        ".",
        "run",
        "mock-weather-mcp-server.py"
      ],
      "env": {
        "MCP_LOG_LEVEL": "ERROR"
      }
    },
    "filesystem": {
      "command": "npx",
      "args": [
        "-y",
        "@modelcontextprotocol/server-filesystem",
        "/tmp"
      ]
    }
  }
}

[!NOTE] An example MCP server script is provided at mcp-servers-config/mock-weather-mcp-server.py.

Usage

Start the Server

# Start with default settings (config: mcp-servers-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
ollama-mcp-bridge --ollama-url http://192.168.1.100:11434

# Combine options
ollama-mcp-bridge --config custom.json --host 0.0.0.0 --port 8080 --ollama-url http://remote-ollama:11434

[!TIP] If installing with uv, you can run the bridge directly using:

ollama-mcp-bridge --config /path/to/custom-config.json --host 0.0.0.0 --port 8080 --ollama-url http://remote-ollama:11434

[!NOTE] This bridge supports both streaming responses and thinking mode. You receive incremental responses as they are generated, with tool calls and intermediate thinking messages automatically proxied between Ollama and all connected MCP tools.

CLI Options

• --config: Path to MCP configuration file (default: mcp-config.json)
• --host: Host to bind the server (default: localhost)
• --port: Port to bind the server (default: 8000)
• --ollama-url: Ollama server URL (default: http://localhost:11434)

API Usage

The API is available at http://localhost:8000.

• Swagger UI docs: http://localhost:8000/docs
• Ollama-compatible endpoints:
  • POST /api/chat — Chat endpoint (same as Ollama API, but with MCP tool support)

[!IMPORTANT] All other standard Ollama endpoints are also transparently proxied by the bridge.

• Health check:
  • GET /health

This bridge acts as a drop-in proxy for the Ollama API, but with all MCP tools from all connected servers available to every request. You can use your existing Ollama clients and libraries, just point them to this bridge instead of your Ollama server.

Example: 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 /docs for interactive API exploration and testing.

Architecture

The application is structured into three main modules:

main.py - CLI Entry Point

• Uses Typer for command-line interface
• Handles configuration and server startup
• Passes configuration to FastAPI app

api.py - FastAPI Application

• Defines API endpoints (/api/chat, /health)
• Manages application lifespan (startup/shutdown)
• Handles HTTP request/response processing

mcp_manager.py - MCP Management

• Loads and manages MCP servers
• Collects and exposes all available tools
• Handles tool calls and integrates results into Ollama responses

utils.py - Utility Functions

• NDJSON parsing, health checks, and other helper functions

Development

Key Dependencies

• FastAPI: Modern web framework for the API
• Typer: CLI framework for command-line interface
• loguru: Structured logging throughout the application
• ollama: Python client for Ollama communication
• mcp: Model Context Protocol client library
• pytest: Testing framework for API validation

Testing

The project has two types of tests:

Unit Tests (GitHub Actions compatible)

# Install test dependencies
uv sync --extra test

# Run unit tests (no server required)
uv run pytest tests/test_unit.py -v

These tests check:

• Configuration file loading
• Module imports and initialization
• Project structure
• Tool definition formats

Integration Tests (require running services)

# 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

These tests check:

• API endpoints with real HTTP requests
• End-to-end functionality with Ollama
• Tool calling and response integration

Manual Testing

# Quick manual test with curl (server must be running)
curl -X GET "http://localhost:8000/health"

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] Tests require the server to be running on localhost:8000. Make sure to start the server before running pytest.

This creates a seamless experience where Ollama can use any tool from any connected MCP server without the client needing to know about the underlying MCP infrastructure.

Inspiration and Credits

This project is based on the basic MCP client from my Medium article: Build an MCP Client in Minutes: Local AI Agents Just Got Real.

The inspiration to create this simple bridge came from this GitHub issue: jonigl/mcp-client-for-ollama#22, suggested by @nyomen.

---

Made with ❤️ by jonigl