Labsco
jonigl logo

Ollama MCP Bridge

★ 95

from jonigl

A bridge API service connecting Ollama with Model Context Protocol (MCP) servers.

🔥🔥🔥🔥✓ VerifiedFreeAdvanced setup
#automation#devops#git#weather#security#monitoring

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

Table of Contents

Features

  • 🚀 Pre-loaded Servers: All MCP servers are connected at startup from JSON configuration
  • 📝 JSON Configuration: Configure multiple servers with complex commands and environments
  • 🌐 Multiple Transport Types: Connect to MCP servers via stdio (local processes), HTTP (StreamableHTTP), or SSE
  • 🎯 Tool Filtering: Filter tools per server with include/exclude modes for fine-grained control
  • 🧩 Config Variable Expansion: Supports ${env:VAR_NAME} and ${workspaceFolder} in config strings
  • 🔗 Tool Integration: Automatic tool call processing and response integration
  • 🔄 Multi-Round Tool Execution: Automatically loops through multiple rounds of tool calls until completion
  • 🛡️ Configurable Tool Limits: Set maximum tool execution rounds to prevent excessive tool calls
  • 🛠️ 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
  • 🔧 Configurable Ollama: Specify custom Ollama server URL via CLI (supports local and cloud models)
  • 🔐 Optional Upstream Headers: Send fixed custom headers (e.g. an API key) with every request to the upstream server
  • ☁️ Cloud Model Support: Works with Ollama cloud models
  • 🔄 Version Check: Automatic check for newer versions with upgrade instructions
  • 🌊 Streaming Responses: Supports incremental streaming of responses to clients
  • 🤔 Thinking Mode: Proxies intermediate "thinking" messages from Ollama and MCP tools
  • ⚡️ FastAPI Backend: Modern async API with automatic documentation
  • 🏗️ Modular Architecture: Clean separation into CLI, API, and MCP management modules
  • 💻 Typer CLI: Clean command-line interface with configurable options
  • 📊 Structured Logging: Uses loguru for comprehensive logging
  • 📦 PyPI Package: Easily installable via pip or uv from PyPI
  • 🗣️ System Prompt Configuration: Allows setting a system prompt for the assistant's behavior
  • 🐳 Multi-Arch Docker Images ✨ NEW: Pre-built linux/amd64 and linux/arm64 images published to GitHub Container Registry on every release

How It Works

  1. Startup: All MCP servers defined in the configuration are loaded and connected
  2. Version Check: At startup, the bridge checks for newer versions and notifies if an update is available
  3. Tool Collection: Tools from all servers are collected and made available to Ollama
  4. Chat Completion Request (/api/chat endpoint only): When a chat completion request is received on /api/chat:
    • The request is forwarded to Ollama (local or cloud) 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 process repeats in a loop until no more tool calls are needed
    • Responses stream to the client in real-time throughout the entire process
    • The final response (with all tool results integrated) is returned to the client
    • This is the only endpoint where MCP server tools are integrated.
  5. Other Endpoints: All other endpoints (except /api/chat, /health, and /version) are fully proxied to the underlying Ollama server with no modification.
  6. Logging: All operations are logged using loguru for debugging and monitoring

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"

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

  • MCP Client for Ollama - A text-based user interface (TUI) client for interacting with MCP servers using Ollama. Features include multi-server support, dynamic model switching, streaming responses, tool management, human-in-the-loop capabilities, thinking mode, full model parameters configuration, custom system prompt and saved preferences. Built for developers working with local LLMs.

  • simple-ollama-chat – A simple, user-friendly chat client for Ollama that works seamlessly with the Ollama MCP Bridge. Lets you interact with models and use all MCP server tools integrated via the bridge, with a clean UI and easy setup. Ideal for quickly testing, chatting, and exploring tool-augmented LLMs through the bridge.

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