<p align="center">
<img src="https://github.com/jonigl/ollama-mcp-bridge/raw/main/misc/ollama-mcp-bridge-logo-512.png" width="256" />
</p>
<p align="center">
<i>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.</i>
</p>
# Ollama MCP Bridge
[](https://pypi.org/project/ollama-mcp-bridge/)
[](https://github.com/jonigl/ollama-mcp-bridge/actions/workflows/test.yml)
[](https://github.com/jonigl/ollama-mcp-bridge/actions/workflows/test-publish.yml)
[](https://github.com/jonigl/ollama-mcp-bridge/actions/workflows/publish.yml)
[](https://www.python.org/downloads/)
## Table of Contents
- [Features](#features)
- [Requirements](#requirements)
- [Installation](#installation)
- [Quick Start](#quick-start)
- [Or, install from PyPI with pip](#or-install-from-pypi-with-pip)
- [Or, run with Docker Compose](#or-run-with-docker-compose)
- [Or, run with Docker only](#or-run-with-docker-only)
- [Or, install from source](#or-install-from-source)
- [How It Works](#how-it-works)
- [Configuration](#configuration)
- [MCP Servers Configuration](#mcp-servers-configuration)
- [CORS Configuration](#cors-configuration)
- [Usage](#usage)
- [Start the Server](#start-the-server)
- [CLI Options](#cli-options)
- [API Usage](#api-usage)
- [Example: Chat](#example-chat)
- [Development](#development)
- [Key Dependencies](#key-dependencies)
- [Testing](#testing)
- [Related Projects](#related-projects)
- [Inspiration and Credits](#inspiration-and-credits)
## Features
- 🚀 **Pre-loaded Servers**: All MCP servers are connected at startup from JSON configuration
- 📝 **JSON Configuration**: Configure multiple servers with complex commands and environments
- 🔗 **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)
- ☁️ **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
## Requirements
- Python >= 3.10.15
- Ollama server running (local or remote)
- MCP server configuration file with at least one MCP server defined (see below for example)
## Installation
You can install `ollama-mcp-bridge` in several ways, depending on your preference:
### Quick Start
Install instantly with [uvx](https://github.com/astral-sh/uv):
```bash
uvx ollama-mcp-bridge
```
### Or, install from PyPI with pip
```bash
pip install --upgrade ollama-mcp-bridge
```
### Or, run with Docker Compose
```bash
docker-compose up
```
This uses the included [docker-compose.yml](./docker-compose.yml) file which:
- Builds the bridge from source using this Dockerfile [Dockerfile](./Dockerfile)
- Connects to Ollama running on the host machine (`host.docker.internal:11434`)
- Maps the configuration file from [./mcp-config.json](./mcp-config.json) (includes mock [weather server for demo](./mock-weather-mcp-server))
- Allows all CORS origins (configurable via `CORS_ORIGINS` environment variable)
### Or, install from source
```bash
# 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):
```bash
# 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. **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
## Configuration
### MCP Servers Configuration
Create an MCP configuration file at `mcp-config.json` with your servers:
```json
{
"mcpServers": {
"weather": {
"command": "uv",
"args": [
"--directory",
"./mock-weather-mcp-server",
"run",
"main.py"
],
"env": {
"MCP_LOG_LEVEL": "ERROR"
}
},
"filesystem": {
"command": "npx",
"args": [
"-y",
"@modelcontextprotocol/server-filesystem",
"/tmp"
]
}
}
}
```
> [!WARNING]
> **Docker Command Limitations**: When running in Docker, MCP servers should use commands available in the container:
> - ✅ `npx` for Node.js-based MCP servers
> - ✅ `uvx` for Python-based MCP servers
> - ✅ Direct executables in the container
> - ❌ `docker` commands (unless Docker-in-Docker is configured)
> - ❌ Local file paths from your host machine
### CORS Configuration
Configure Cross-Origin Resource Sharing (CORS) to allow requests from your frontend applications:
```bash
# 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
```
**Environment Variables:**
- `CORS_ORIGINS`: Comma-separated list of allowed origins (default: `*`)
- `*` allows all origins (shows warning in logs)
- Example: `CORS_ORIGINS="http://localhost:3000,https://myapp.com" ollama-mcp-bridge`
- `MAX_TOOL_ROUNDS`: Maximum number of tool execution rounds (default: unlimited)
- Can be overridden with `--max-tool-rounds` CLI parameter (CLI takes precedence)
- Example: `MAX_TOOL_ROUNDS=5 ollama-mcp-bridge`
- `OLLAMA_URL`: URL of the Ollama server (default: `http://localhost:11434`)
- Can be overridden with `--ollama-url` CLI parameter
- Useful for Docker deployments and configuration management
- Example: `OLLAMA_URL=http://192.168.1.100:11434 ollama-mcp-bridge`
- `SYSTEM_PROMPT`: Optional system prompt to prepend to all forwarded `/api/chat` requests
- Can be set via the `SYSTEM_PROMPT` environment variable or `--system-prompt` CLI flag
- If provided, the bridge will prepend a system message (role: `system`) to the beginning of the `messages` array for `/api/chat` requests unless the request already starts with a system message.
- Example: `SYSTEM_PROMPT="You are a concise assistant." ollama-mcp-bridge`
**CORS Logging:**
- The bridge logs CORS configuration at startup
- Shows warning when using `*` (all origins)
- Shows allowed origins when properly configured
> [!WARNING]
> Using `CORS_ORIGINS="*"` allows all origins and is not recommended for production. Always specify exact origins for security.
> [!NOTE]
> An example MCP server script is provided at [mock-weather-mcp-server/main.py](mock-weather-mcp-server/main.py).
## Usage
### Start the Server
```bash
# 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
# 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
# Check version and available updates
ollama-mcp-bridge --version
```
> [!TIP]
> If using `uvx` to run the bridge, you have to specify the command as `uvx ollama-mcp-bridge` instead of just `ollama-mcp-bridge`.
> [!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: `0.0.0.0`)
- `--port`: Port to bind the server (default: `8000`)
- `--ollama-url`: Ollama server URL (default: `http://localhost:11434`)
- `--max-tool-rounds`: Maximum tool execution rounds (default: unlimited)
- `--reload`: Enable auto-reload during development
- `--version`: Show version information, check for updates and exit
- `--system-prompt`: Optional system prompt to prepend to `/api/chat` requests (default: none)
### API Usage
The API is available at `http://localhost:8000`.
- **Swagger UI docs:** [http://localhost:8000/docs](http://localhost:8000/docs)
- **Ollama-compatible endpoints:**
- `POST /api/chat` — Chat endpoint (same as Ollama API, but with MCP tool support)
- **This is the only endpoint where MCP server tools are integrated.** All tool calls are handled and responses are merged transparently for the client.
- **All other endpoints** (except `/api/chat`, `/health`, and `/version`) are fully proxied to the underlying Ollama server with no modification. You can use your existing Ollama clients and libraries as usual.
- **Bridge-specific endpoints:**
- `GET /health` — Health check endpoint (not proxied)
- `GET /version` — Version information and update check
> [!IMPORTANT]
> `/api/chat` is the only endpoint with MCP tool integration. All other endpoints are transparently proxied to Ollama. `/health` and `/version` are specific to the bridge.
This bridge acts as a drop-in proxy for the Ollama API, but with all MCP tools from all connected servers available to every `/api/chat` request. The bridge automatically handles multiple rounds of tool execution until completion, streaming responses in real-time. You can use your existing Ollama clients and libraries with both local and cloud Ollama models, just point them to this bridge instead of your Ollama server.
### Example: Chat
```bash
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.
## 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)
```bash
# 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)
```bash
# 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
```bash
# 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.
## Related Projects
- [**MCP Client for Ollama**](https://github.com/jonigl/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.
## 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](https://medium.com/@jonigl/build-an-mcp-client-in-minutes-local-ai-agents-just-got-real-a10e186a560f).
The inspiration to create this simple bridge came from this GitHub issue: [jonigl/mcp-client-for-ollama#22](https://github.com/jonigl/mcp-client-for-ollama/issues/22), suggested by [@nyomen](https://github.com/nyomen).
---
Made with ❤️ by [jonigl](https://github.com/jonigl)
Raw data
{
"_id": null,
"home_page": null,
"name": "ollama-mcp-bridge",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.10",
"maintainer_email": null,
"keywords": "ai, api, bridge, fastapi, llm, local-llm, mcp, model-context-protocol, ollama, ollama-api, ollama-mcp, proxy, tools",
"author": "Jonathan Gast\u00f3n L\u00f6wenstern",
"author_email": null,
"download_url": "https://files.pythonhosted.org/packages/af/9f/7b4e6341c368daa70a337a4d93746f03b4b5aed6c5b150d109c517157dc0/ollama_mcp_bridge-0.7.0.tar.gz",
"platform": null,
"description": "<p align=\"center\">\n\n <img src=\"https://github.com/jonigl/ollama-mcp-bridge/raw/main/misc/ollama-mcp-bridge-logo-512.png\" width=\"256\" />\n</p>\n<p align=\"center\">\n<i>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.</i>\n</p>\n\n# Ollama MCP Bridge\n\n[](https://pypi.org/project/ollama-mcp-bridge/)\n[](https://github.com/jonigl/ollama-mcp-bridge/actions/workflows/test.yml)\n[](https://github.com/jonigl/ollama-mcp-bridge/actions/workflows/test-publish.yml)\n[](https://github.com/jonigl/ollama-mcp-bridge/actions/workflows/publish.yml)\n[](https://www.python.org/downloads/)\n\n\n## Table of Contents\n\n- [Features](#features)\n- [Requirements](#requirements)\n- [Installation](#installation)\n - [Quick Start](#quick-start)\n - [Or, install from PyPI with pip](#or-install-from-pypi-with-pip)\n - [Or, run with Docker Compose](#or-run-with-docker-compose)\n - [Or, run with Docker only](#or-run-with-docker-only)\n - [Or, install from source](#or-install-from-source)\n- [How It Works](#how-it-works)\n- [Configuration](#configuration)\n - [MCP Servers Configuration](#mcp-servers-configuration)\n - [CORS Configuration](#cors-configuration)\n- [Usage](#usage)\n - [Start the Server](#start-the-server)\n - [CLI Options](#cli-options)\n - [API Usage](#api-usage)\n - [Example: Chat](#example-chat)\n- [Development](#development)\n - [Key Dependencies](#key-dependencies)\n - [Testing](#testing)\n- [Related Projects](#related-projects)\n- [Inspiration and Credits](#inspiration-and-credits)\n\n## Features\n\n- \ud83d\ude80 **Pre-loaded Servers**: All MCP servers are connected at startup from JSON configuration\n- \ud83d\udcdd **JSON Configuration**: Configure multiple servers with complex commands and environments\n- \ud83d\udd17 **Tool Integration**: Automatic tool call processing and response integration\n- \ud83d\udd04 **Multi-Round Tool Execution**: Automatically loops through multiple rounds of tool calls until completion\n- \ud83d\udee1\ufe0f **Configurable Tool Limits**: Set maximum tool execution rounds to prevent excessive tool calls\n- \ud83d\udee0\ufe0f **All Tools Available**: Ollama can use any tool from any connected server simultaneously\n- \ud83d\udd0c **Complete API Compatibility**: `/api/chat` adds tools while all other Ollama API endpoints are transparently proxied\n- \ud83d\udd27 **Configurable Ollama**: Specify custom Ollama server URL via CLI (supports local and cloud models)\n- \u2601\ufe0f **Cloud Model Support**: Works with Ollama cloud models\n- \ud83d\udd04 **Version Check**: Automatic check for newer versions with upgrade instructions\n- \ud83c\udf0a **Streaming Responses**: Supports incremental streaming of responses to clients\n- \ud83e\udd14 **Thinking Mode**: Proxies intermediate \"thinking\" messages from Ollama and MCP tools\n- \u26a1\ufe0f **FastAPI Backend**: Modern async API with automatic documentation\n- \ud83c\udfd7\ufe0f **Modular Architecture**: Clean separation into CLI, API, and MCP management modules\n- \ud83d\udcbb **Typer CLI**: Clean command-line interface with configurable options\n- \ud83d\udcca **Structured Logging**: Uses loguru for comprehensive logging\n- \ud83d\udce6 **PyPI Package**: Easily installable via pip or uv from PyPI\n- \ud83d\udde3\ufe0f **System Prompt Configuration**: Allows setting a system prompt for the assistant's behavior\n\n## Requirements\n\n- Python >= 3.10.15\n- Ollama server running (local or remote)\n- MCP server configuration file with at least one MCP server defined (see below for example)\n\n## Installation\n\nYou can install `ollama-mcp-bridge` in several ways, depending on your preference:\n\n### Quick Start\nInstall instantly with [uvx](https://github.com/astral-sh/uv):\n```bash\nuvx ollama-mcp-bridge\n```\n\n### Or, install from PyPI with pip\n```bash\npip install --upgrade ollama-mcp-bridge\n```\n\n### Or, run with Docker Compose\n\n```bash\ndocker-compose up\n```\n\nThis uses the included [docker-compose.yml](./docker-compose.yml) file which:\n- Builds the bridge from source using this Dockerfile [Dockerfile](./Dockerfile)\n- Connects to Ollama running on the host machine (`host.docker.internal:11434`)\n- Maps the configuration file from [./mcp-config.json](./mcp-config.json) (includes mock [weather server for demo](./mock-weather-mcp-server))\n- Allows all CORS origins (configurable via `CORS_ORIGINS` environment variable)\n\n\n### Or, install from source\n\n```bash\n# Clone the repository\ngit clone https://github.com/jonigl/ollama-mcp-bridge.git\ncd ollama-mcp-bridge\n\n# Install dependencies using uv\nuv sync\n\n# Start Ollama (if not already running)\nollama serve\n\n# Run the bridge (preferred)\nollama-mcp-bridge\n```\n\nIf you want to install the project in editable mode (for development):\n\n```bash\n# Install the project in editable mode\nuv tool install --editable .\n# Run it like this:\nollama-mcp-bridge\n```\n\n## How It Works\n\n1. **Startup**: All MCP servers defined in the configuration are loaded and connected\n2. **Version Check**: At startup, the bridge checks for newer versions and notifies if an update is available\n3. **Tool Collection**: Tools from all servers are collected and made available to Ollama\n4. **Chat Completion Request (`/api/chat` endpoint only)**: When a chat completion request is received on `/api/chat`:\n - The request is forwarded to Ollama (local or cloud) along with the list of all available tools\n - If Ollama chooses to invoke any tools, those tool calls are executed through the corresponding MCP servers\n - Tool responses are fed back to Ollama\n - The process repeats in a loop until no more tool calls are needed\n - Responses stream to the client in real-time throughout the entire process\n - The final response (with all tool results integrated) is returned to the client\n - **This is the only endpoint where MCP server tools are integrated.**\n5. **Other Endpoints**: All other endpoints (except `/api/chat`, `/health`, and `/version`) are fully proxied to the underlying Ollama server with no modification.\n6. **Logging**: All operations are logged using loguru for debugging and monitoring\n\n## Configuration\n\n### MCP Servers Configuration\n\nCreate an MCP configuration file at `mcp-config.json` with your servers:\n\n```json\n{\n \"mcpServers\": {\n \"weather\": {\n \"command\": \"uv\",\n \"args\": [\n \"--directory\",\n \"./mock-weather-mcp-server\",\n \"run\",\n \"main.py\"\n ],\n \"env\": {\n \"MCP_LOG_LEVEL\": \"ERROR\"\n }\n },\n \"filesystem\": {\n \"command\": \"npx\",\n \"args\": [\n \"-y\",\n \"@modelcontextprotocol/server-filesystem\",\n \"/tmp\"\n ]\n }\n }\n}\n```\n\n> [!WARNING]\n> **Docker Command Limitations**: When running in Docker, MCP servers should use commands available in the container:\n> - \u2705 `npx` for Node.js-based MCP servers\n> - \u2705 `uvx` for Python-based MCP servers\n> - \u2705 Direct executables in the container\n> - \u274c `docker` commands (unless Docker-in-Docker is configured)\n> - \u274c Local file paths from your host machine\n\n### CORS Configuration\n\nConfigure Cross-Origin Resource Sharing (CORS) to allow requests from your frontend applications:\n\n```bash\n# Allow all origins (default, not recommended for production)\nollama-mcp-bridge\n\n# Allow specific origins\nCORS_ORIGINS=\"http://localhost:3000,https://myapp.com\" ollama-mcp-bridge\n\n# Allow multiple origins with different ports\nCORS_ORIGINS=\"http://localhost:3000,http://localhost:8080,https://app.example.com\" ollama-mcp-bridge\n```\n\n**Environment Variables:**\n- `CORS_ORIGINS`: Comma-separated list of allowed origins (default: `*`)\n - `*` allows all origins (shows warning in logs)\n - Example: `CORS_ORIGINS=\"http://localhost:3000,https://myapp.com\" ollama-mcp-bridge`\n- `MAX_TOOL_ROUNDS`: Maximum number of tool execution rounds (default: unlimited)\n - Can be overridden with `--max-tool-rounds` CLI parameter (CLI takes precedence)\n - Example: `MAX_TOOL_ROUNDS=5 ollama-mcp-bridge`\n- `OLLAMA_URL`: URL of the Ollama server (default: `http://localhost:11434`)\n - Can be overridden with `--ollama-url` CLI parameter\n - Useful for Docker deployments and configuration management\n - Example: `OLLAMA_URL=http://192.168.1.100:11434 ollama-mcp-bridge`\n- `SYSTEM_PROMPT`: Optional system prompt to prepend to all forwarded `/api/chat` requests\n - Can be set via the `SYSTEM_PROMPT` environment variable or `--system-prompt` CLI flag\n - If provided, the bridge will prepend a system message (role: `system`) to the beginning of the `messages` array for `/api/chat` requests unless the request already starts with a system message.\n - Example: `SYSTEM_PROMPT=\"You are a concise assistant.\" ollama-mcp-bridge`\n\n**CORS Logging:**\n- The bridge logs CORS configuration at startup\n- Shows warning when using `*` (all origins)\n- Shows allowed origins when properly configured\n\n> [!WARNING]\n> Using `CORS_ORIGINS=\"*\"` allows all origins and is not recommended for production. Always specify exact origins for security.\n\n> [!NOTE]\n> An example MCP server script is provided at [mock-weather-mcp-server/main.py](mock-weather-mcp-server/main.py).\n\n## Usage\n\n### Start the Server\n```bash\n# Start with default settings (config: ./mcp-config.json, host: 0.0.0.0, port: 8000)\nollama-mcp-bridge\n\n# Start with custom configuration file\nollama-mcp-bridge --config /path/to/custom-config.json\n\n# Custom host and port\nollama-mcp-bridge --host 0.0.0.0 --port 8080\n\n# Custom Ollama server URL (local or cloud)\nollama-mcp-bridge --ollama-url http://192.168.1.100:11434\n\n# Limit tool execution rounds (prevents excessive tool calls)\nollama-mcp-bridge --max-tool-rounds 5\n\n# Set a system prompt to prepend to all /api/chat requests\nollama-mcp-bridge --system-prompt \"You are a concise assistant.\"\n\n# Combine options\nollama-mcp-bridge --config custom.json --host 0.0.0.0 --port 8080 --ollama-url http://remote-ollama:11434 --max-tool-rounds 10\n\n# Check version and available updates\nollama-mcp-bridge --version\n```\n\n> [!TIP]\n> If using `uvx` to run the bridge, you have to specify the command as `uvx ollama-mcp-bridge` instead of just `ollama-mcp-bridge`.\n\n> [!NOTE]\n> 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.\n\n### CLI Options\n- `--config`: Path to MCP configuration file (default: `mcp-config.json`)\n- `--host`: Host to bind the server (default: `0.0.0.0`)\n- `--port`: Port to bind the server (default: `8000`)\n- `--ollama-url`: Ollama server URL (default: `http://localhost:11434`)\n- `--max-tool-rounds`: Maximum tool execution rounds (default: unlimited)\n- `--reload`: Enable auto-reload during development\n- `--version`: Show version information, check for updates and exit\n- `--system-prompt`: Optional system prompt to prepend to `/api/chat` requests (default: none)\n### API Usage\n\nThe API is available at `http://localhost:8000`.\n\n- **Swagger UI docs:** [http://localhost:8000/docs](http://localhost:8000/docs)\n- **Ollama-compatible endpoints:**\n - `POST /api/chat` \u2014 Chat endpoint (same as Ollama API, but with MCP tool support)\n - **This is the only endpoint where MCP server tools are integrated.** All tool calls are handled and responses are merged transparently for the client.\n - **All other endpoints** (except `/api/chat`, `/health`, and `/version`) are fully proxied to the underlying Ollama server with no modification. You can use your existing Ollama clients and libraries as usual.\n- **Bridge-specific endpoints:**\n - `GET /health` \u2014 Health check endpoint (not proxied)\n - `GET /version` \u2014 Version information and update check\n\n> [!IMPORTANT]\n> `/api/chat` is the only endpoint with MCP tool integration. All other endpoints are transparently proxied to Ollama. `/health` and `/version` are specific to the bridge.\n\nThis bridge acts as a drop-in proxy for the Ollama API, but with all MCP tools from all connected servers available to every `/api/chat` request. The bridge automatically handles multiple rounds of tool execution until completion, streaming responses in real-time. You can use your existing Ollama clients and libraries with both local and cloud Ollama models, just point them to this bridge instead of your Ollama server.\n\n### Example: Chat\n```bash\ncurl -N -X POST http://localhost:8000/api/chat \\\n -H \"accept: application/json\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\n \"model\": \"qwen3:0.6b\",\n \"messages\": [\n {\n \"role\": \"system\",\n \"content\": \"You are a weather assistant.\"\n },\n {\n \"role\": \"user\",\n \"content\": \"What is the weather like in Paris today?\"\n }\n ],\n \"think\": true,\n \"stream\": true,\n \"options\": {\n \"temperature\": 0.7,\n \"top_p\": 0.9\n }\n }'\n```\n\n> [!TIP]\n> Use `/docs` for interactive API exploration and testing.\n\n\n## Development\n\n### Key Dependencies\n- **FastAPI**: Modern web framework for the API\n- **Typer**: CLI framework for command-line interface\n- **loguru**: Structured logging throughout the application\n- **ollama**: Python client for Ollama communication\n- **mcp**: Model Context Protocol client library\n- **pytest**: Testing framework for API validation\n\n### Testing\n\nThe project has two types of tests:\n\n#### Unit Tests (GitHub Actions compatible)\n```bash\n# Install test dependencies\nuv sync --extra test\n\n# Run unit tests (no server required)\nuv run pytest tests/test_unit.py -v\n```\n\nThese tests check:\n- Configuration file loading\n- Module imports and initialization\n- Project structure\n- Tool definition formats\n\n#### Integration Tests (require running services)\n```bash\n# First, start the server in one terminal\nollama-mcp-bridge\n\n# Then in another terminal, run the integration tests\nuv run pytest tests/test_api.py -v\n```\n\nThese tests check:\n- API endpoints with real HTTP requests\n- End-to-end functionality with Ollama\n- Tool calling and response integration\n\n#### Manual Testing\n```bash\n# Quick manual test with curl (server must be running)\ncurl -X GET \"http://localhost:8000/health\"\n\n# Check version information and update status\ncurl -X GET \"http://localhost:8000/version\"\n\ncurl -X POST \"http://localhost:8000/api/chat\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\"model\": \"qwen3:0.6b\", \"messages\": [{\"role\": \"user\", \"content\": \"What tools are available?\"}]}'\n```\n\n> [!NOTE]\n> Tests require the server to be running on localhost:8000. Make sure to start the server before running pytest.\n\n## Related Projects\n\n- [**MCP Client for Ollama**](https://github.com/jonigl/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.\n\n## Inspiration and Credits\n\nThis project is based on the basic MCP client from my Medium article: [Build an MCP Client in Minutes: Local AI Agents Just Got Real](https://medium.com/@jonigl/build-an-mcp-client-in-minutes-local-ai-agents-just-got-real-a10e186a560f).\n\nThe inspiration to create this simple bridge came from this GitHub issue: [jonigl/mcp-client-for-ollama#22](https://github.com/jonigl/mcp-client-for-ollama/issues/22), suggested by [@nyomen](https://github.com/nyomen).\n\n---\n\nMade with \u2764\ufe0f by [jonigl](https://github.com/jonigl)\n",
"bugtrack_url": null,
"license": null,
"summary": "Bridge API service connecting Ollama with Model Context Protocol (MCP) servers",
"version": "0.7.0",
"project_urls": {
"Documentation": "https://github.com/jonigl/ollama-mcp-bridge#readme",
"Issues": "https://github.com/jonigl/ollama-mcp-bridge/issues",
"Source": "https://github.com/jonigl/ollama-mcp-bridge"
},
"split_keywords": [
"ai",
" api",
" bridge",
" fastapi",
" llm",
" local-llm",
" mcp",
" model-context-protocol",
" ollama",
" ollama-api",
" ollama-mcp",
" proxy",
" tools"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "514c528ed69aa453bd873fabc21fe129945d4a33e1abf18665a7ba0221124da6",
"md5": "5db80f5c031a377fb29771cb15028739",
"sha256": "85ee7bf82426a983b3f3f6e7f6bc34f4e995e0afb5d2ea0481e73a5b86270fc1"
},
"downloads": -1,
"filename": "ollama_mcp_bridge-0.7.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "5db80f5c031a377fb29771cb15028739",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.10",
"size": 19975,
"upload_time": "2025-10-23T18:38:17",
"upload_time_iso_8601": "2025-10-23T18:38:17.117556Z",
"url": "https://files.pythonhosted.org/packages/51/4c/528ed69aa453bd873fabc21fe129945d4a33e1abf18665a7ba0221124da6/ollama_mcp_bridge-0.7.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "af9f7b4e6341c368daa70a337a4d93746f03b4b5aed6c5b150d109c517157dc0",
"md5": "3078de01ce0e83f4000aa74e1c849ea0",
"sha256": "04b988a51ed6b3fc74c5da1aebaa1b4f9420db27823c6ac7bea971ff20317c01"
},
"downloads": -1,
"filename": "ollama_mcp_bridge-0.7.0.tar.gz",
"has_sig": false,
"md5_digest": "3078de01ce0e83f4000aa74e1c849ea0",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.10",
"size": 803810,
"upload_time": "2025-10-23T18:38:18",
"upload_time_iso_8601": "2025-10-23T18:38:18.298775Z",
"url": "https://files.pythonhosted.org/packages/af/9f/7b4e6341c368daa70a337a4d93746f03b4b5aed6c5b150d109c517157dc0/ollama_mcp_bridge-0.7.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-10-23 18:38:18",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "jonigl",
"github_project": "ollama-mcp-bridge#readme",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "ollama-mcp-bridge"
}
JSON
