Skip to content
Back to search

ollama-mcp-bridge

Extend the Ollama API with dynamic AI tool integration from multiple MCP (Model Context Protocol) servers. Fully compatible, transparent, and developer-friendly, ideal for building powerful local LLM applications, AI agents, and custom chatbots

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/jonigl--ollama-mcp-bridge/badge.svg)](/listings/jonigl--ollama-mcp-bridge)

HTML

<a href="/listings/jonigl--ollama-mcp-bridge"><img src="/api/listings/jonigl--ollama-mcp-bridge/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

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):

uvx ollama-mcp-bridge

Or, install from PyPI with pip

pip install --upgrade ollama-mcp-bridge

Or, run with Docker Compose

docker compose up

This uses the included [docker-compose.yml](./docker-compose.yml) file which: - Builds the bridge from source using the [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)) - Exposes port `8000` on the host - Allows all CORS origins (configurable via `CORS_ORIGINS` environment variable) - Supports configurable Ollama request timeouts via `OLLAMA_PROXY_TIMEOUT`

> [!TIP] > To skip the local build and use the pre-built image from GitHub Container Registry instead, replace the `build:` block in `docker-compose.yml` with: > ```yaml > image: ghcr.io/jonigl/ollama-mcp-bridge:latest > ```

Or, run with Docker only

> [!NOTE] > ✨ **NEW**: Pre-built multi-arch Docker images (`linux/amd64` and `linux/arm64`) are now published automatically to the GitHub Container Registry on every release. No local build required!

Pre-built multi-arch images (`linux/amd64` and `linux/arm64`) are published to the [GitHub Container Registry](https://github.com/jonigl/ollama-mcp-bridge/pkgs/container/ollama-mcp-bridge) on every release. Available tags: - `latest` — most recent stable release - `vX.Y.Z` — specific version (e.g. `v0.10.0`) - `sha-<commit>` — exact commit SHA build

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

Key flags: - `-p 8000:8000` — exposes the bridge on your host at port `8000` - `-e OLLAMA_URL=http://host.docker.internal:11434` — routes Ollama traffic to the host machine (required on macOS and Windows; on Linux use `--network host` or the host's IP instead) - `-v "$PWD/mcp-config.json:/mcp-config.json"` — mounts your local config into the container - `-v "$PWD/mock-weather-mcp-server:/mock-weather-mcp-server"` — mounts the mock MCP server **without** `:ro` so `uv` can create its `.venv` inside the directory - `-w /` — sets the working directory to `/` so relative paths in `mcp-config.json` resolve correctly

> [!NOTE] > On Linux, `host.docker.internal` may not resolve automatically. Use `--network host` and keep `OLLAMA_URL=http://localhost:11434`, or replace it with your host's LAN IP.

Or, install from source

# 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

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

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 571 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

  1. <p align="center">
  2. <img src="https://github.com/jonigl/ollama-mcp-bridge/raw/main/misc/ollama-mcp-bridge-logo-512.png" width="256" />
  3. </p>
  4. <p align="center">
  5. <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>
  6. </p>
  7. # Ollama MCP Bridge
  8. [![PyPI - Package Version](https://img.shields.io/pypi/v/ollama-mcp-bridge?label=ollama-mcp-bridge)](https://pypi.org/project/ollama-mcp-bridge/)
  9. [![CI](https://github.com/jonigl/ollama-mcp-bridge/actions/workflows/ci.yml/badge.svg)](https://github.com/jonigl/ollama-mcp-bridge/actions/workflows/ci.yml)
  10. [![Test Publish](https://github.com/jonigl/ollama-mcp-bridge/actions/workflows/test-publish.yml/badge.svg)](https://github.com/jonigl/ollama-mcp-bridge/actions/workflows/test-publish.yml)
  11. [![Publish](https://github.com/jonigl/ollama-mcp-bridge/actions/workflows/publish.yml/badge.svg)](https://github.com/jonigl/ollama-mcp-bridge/actions/workflows/publish.yml)
  12. [![Python 3.10+](https://img.shields.io/badge/Python-3.10+-blue.svg)](https://www.python.org/downloads/)
  13. ![License](https://img.shields.io/badge/License-MIT-green.svg)
  14. > **📖 Full documentation: <https://jonigl.github.io/ollama-mcp-bridge/>**
  15. >
  16. > Installation, configuration reference, architecture notes and a code reference, all searchable.
  17. ## Table of Contents
  18. - [Features](#features)
  19. - [Requirements](#requirements)
  20. - [Installation](#installation)
  21. - [Quick Start](#quick-start)
  22. - [Or, install from PyPI with pip](#or-install-from-pypi-with-pip)
  23. - [Or, run with Docker Compose](#or-run-with-docker-compose)
  24. - **✨NEW** [Or, run with Docker only](#or-run-with-docker-only)
  25. - [Or, install from source](#or-install-from-source)
  26. - [How It Works](#how-it-works)
  27. - [Configuration](#configuration)
  28. - [MCP Servers Configuration](#mcp-servers-configuration)
  29. - [Tool Filtering](#tool-filtering)
  30. - [Variable Expansion](#variable-expansion)
  31. - [CORS Configuration](#cors-configuration)
  32. - [Environment Variables](#environment-variables)
  33. - [Usage](#usage)
  34. - [Start the Server](#start-the-server)
  35. - [CLI Options](#cli-options)
  36. - [API Usage](#api-usage)
  37. - [Example: Chat](#example-chat)
  38. - [Development](#development)
  39. - [Key Dependencies](#key-dependencies)
  40. - [Testing](#testing)
  41. - [Contributing](#contributing)
  42. - [Related Projects](#related-projects)
  43. - [Inspiration and Credits](#inspiration-and-credits)
  44. ## Features
  45. - 🚀 **Pre-loaded Servers**: All MCP servers are connected at startup from JSON configuration
  46. - 📝 **JSON Configuration**: Configure multiple servers with complex commands and environments
  47. - 🌐 **Multiple Transport Types**: Connect to MCP servers via stdio (local processes), HTTP (StreamableHTTP), or SSE
  48. - 🎯 **Tool Filtering**: Filter tools per server with include/exclude modes for fine-grained control
  49. - 🧩 **Config Variable Expansion**: Supports `${env:VAR_NAME}` and `${workspaceFolder}` in config strings
  50. - 🔗 **Tool Integration**: Automatic tool call processing and response integration
  51. - 🔄 **Multi-Round Tool Execution**: Automatically loops through multiple rounds of tool calls until completion
  52. - 🛡️ **Configurable Tool Limits**: Set maximum tool execution rounds to prevent excessive tool calls
  53. - 🛠️ **All Tools Available**: Ollama can use any tool from any connected server simultaneously
  54. - 🔌 **Complete API Compatibility**: `/api/chat` adds tools while all other Ollama API endpoints are transparently proxied
  55. - 🔧 **Configurable Ollama**: Specify custom Ollama server URL via CLI (supports local and cloud models)
  56. - 🔐 **Optional Upstream Headers**: Send fixed custom headers (e.g. an API key) with every request to the upstream server
  57. - ☁️ **Cloud Model Support**: Works with Ollama cloud models
  58. - 🔄 **Version Check**: Automatic check for newer versions with upgrade instructions
  59. - 🌊 **Streaming Responses**: Supports incremental streaming of responses to clients
  60. - 🤔 **Thinking Mode**: Proxies intermediate "thinking" messages from Ollama and MCP tools
  61. - ⚡️ **FastAPI Backend**: Modern async API with automatic documentation
  62. - 🏗️ **Modular Architecture**: Clean separation into CLI, API, and MCP management modules
  63. - 💻 **Typer CLI**: Clean command-line interface with configurable options
  64. - 📊 **Structured Logging**: Uses loguru for comprehensive logging
  65. - 📦 **PyPI Package**: Easily installable via pip or uv from PyPI
  66. - 🗣️ **System Prompt Configuration**: Allows setting a system prompt for the assistant's behavior
  67. - 🐳 **Multi-Arch Docker Images** ✨ **NEW**: Pre-built `linux/amd64` and `linux/arm64` images published to GitHub Container Registry on every release
  68. ## Requirements
  69. - Python >= 3.10.15
  70. - Ollama server running (local or remote)
  71. - MCP server configuration file with at least one MCP server defined (see below for example)
  72. ## Installation
  73. You can install `ollama-mcp-bridge` in several ways, depending on your preference:
  74. ### Quick Start
  75. Install instantly with [uvx](https://github.com/astral-sh/uv):
  76. ```bash
  77. uvx ollama-mcp-bridge
  78. ```
  79. ### Or, install from PyPI with pip
  80. ```bash
  81. pip install --upgrade ollama-mcp-bridge
  82. ```
  83. ### Or, run with Docker Compose
  84. ```bash
  85. docker compose up
  86. ```
  87. This uses the included [docker-compose.yml](./docker-compose.yml) file which:
  88. - Builds the bridge from source using the [Dockerfile](./Dockerfile)
  89. - Connects to Ollama running on the host machine (`host.docker.internal:11434`)
  90. - Maps the configuration file from [./mcp-config.json](./mcp-config.json) (includes mock [weather server for demo](./mock-weather-mcp-server))
  91. - Exposes port `8000` on the host
  92. - Allows all CORS origins (configurable via `CORS_ORIGINS` environment variable)
  93. - Supports configurable Ollama request timeouts via `OLLAMA_PROXY_TIMEOUT`
  94. > [!TIP]
  95. > To skip the local build and use the pre-built image from GitHub Container Registry instead, replace the `build:` block in `docker-compose.yml` with:
  96. > ```yaml
  97. > image: ghcr.io/jonigl/ollama-mcp-bridge:latest
  98. > ```
  99. ### Or, run with Docker only
  100. > [!NOTE]
  101. > ✨ **NEW**: Pre-built multi-arch Docker images (`linux/amd64` and `linux/arm64`) are now published automatically to the GitHub Container Registry on every release. No local build required!
  102. Pre-built multi-arch images (`linux/amd64` and `linux/arm64`) are published to the [GitHub Container Registry](https://github.com/jonigl/ollama-mcp-bridge/pkgs/container/ollama-mcp-bridge) on every release. Available tags:
  103. - `latest` — most recent stable release
  104. - `vX.Y.Z` — specific version (e.g. `v0.10.0`)
  105. - `sha-<commit>` — exact commit SHA build
  106. ```bash
  107. docker run -p 8000:8000 \
  108. -e OLLAMA_URL=http://host.docker.internal:11434 \
  109. -v "$PWD/mcp-config.json:/mcp-config.json" \
  110. -v "$PWD/mock-weather-mcp-server:/mock-weather-mcp-server" \
  111. -w / \
  112. ghcr.io/jonigl/ollama-mcp-bridge:latest
  113. ```
  114. Key flags:
  115. - `-p 8000:8000` — exposes the bridge on your host at port `8000`
  116. - `-e OLLAMA_URL=http://host.docker.internal:11434` — routes Ollama traffic to the host machine (required on macOS and Windows; on Linux use `--network host` or the host's IP instead)
  117. - `-v "$PWD/mcp-config.json:/mcp-config.json"` — mounts your local config into the container
  118. - `-v "$PWD/mock-weather-mcp-server:/mock-weather-mcp-server"` — mounts the mock MCP server **without** `:ro` so `uv` can create its `.venv` inside the directory
  119. - `-w /` — sets the working directory to `/` so relative paths in `mcp-config.json` resolve correctly
  120. > [!NOTE]
  121. > On Linux, `host.docker.internal` may not resolve automatically. Use `--network host` and keep `OLLAMA_URL=http://localhost:11434`, or replace it with your host's LAN IP.
  122. ### Or, install from source
  123. ```bash
  124. # Clone the repository
  125. git clone https://github.com/jonigl/ollama-mcp-bridge.git
  126. cd ollama-mcp-bridge
  127. # Start Ollama (if not already running)
  128. ollama serve
  129. # Run the bridge
  130. uv run ollama-mcp-bridge
  131. ```
  132. If you want to install the project in editable mode (for development):
  133. ```bash
  134. # Install the project in editable mode
  135. uv tool install --editable .
  136. # Run it like this:
  137. ollama-mcp-bridge
  138. ```
  139. ## How It Works
  140. 1. **Startup**: All MCP servers defined in the configuration are loaded and connected
  141. 2. **Version Check**: At startup, the bridge checks for newer versions and notifies if an update is available
  142. 3. **Tool Collection**: Tools from all servers are collected and made available to Ollama
  143. 4. **Chat Completion Request (`/api/chat` endpoint only)**: When a chat completion request is received on `/api/chat`:
  144. - The request is forwarded to Ollama (local or cloud) along with the list of all available tools
  145. - If Ollama chooses to invoke any tools, those tool calls are executed through the corresponding MCP servers
  146. - Tool responses are fed back to Ollama
  147. - The process repeats in a loop until no more tool calls are needed
  148. - Responses stream to the client in real-time throughout the entire process
  149. - The final response (with all tool results integrated) is returned to the client
  150. - **This is the only endpoint where MCP server tools are integrated.**
  151. 5. **Other Endpoints**: All other endpoints (except `/api/chat`, `/health`, and `/version`) are fully proxied to the underlying Ollama server with no modification.
  152. 6. **Logging**: All operations are logged using loguru for debugging and monitoring
  153. ## Configuration
  154. ### MCP Servers Configuration
  155. You can configure MCP servers in three ways:
  156. - **Local process (stdio)**: `{"command": "...", "args": [...], "env": {...}}`
  157. - **Remote endpoint (StreamableHTTP)**: `{"url": "https://..."}` - Uses StreamableHTTP by default
  158. - **Remote endpoint (SSE)**: `{"url": "https://.../sse"}` - If the URL ends with `/sse`, the bridge connects via Server-Sent Events
  159. Create an MCP configuration file at `mcp-config.json` with your servers:
  160. ```json
  161. {
  162. "mcpServers": {
  163. "weather": {
  164. "command": "uv",
  165. "args": [
  166. "--directory",
  167. "./mock-weather-mcp-server",
  168. "run",
  169. "main.py"
  170. ],
  171. "env": {
  172. "MCP_LOG_LEVEL": "ERROR"
  173. },
  174. "toolFilter": {
  175. "mode": "include",
  176. "tools": ["get_current_temperature", "get_forecast"]
  177. }
  178. },
  179. "remote_streamable_http": {
  180. "url": "https://example.com/mcp"
  181. },
  182. "remote_sse": {
  183. "url": "https://example.com/sse"
  184. },
  185. "filesystem": {
  186. "command": "npx",
  187. "args": [
  188. "-y",
  189. "@modelcontextprotocol/server-filesystem",
  190. "/tmp"
  191. ],
  192. "toolFilter": {
  193. "mode": "exclude",
  194. "tools": ["delete_file", "write_file"]
  195. }
  196. }
  197. }
  198. }
  199. ```
  200. #### Tool Filtering
  201. You can filter which tools from an MCP server are made available to Ollama using the optional `toolFilter` configuration:
  202. - **`toolFilter`** (optional): Object with filtering options
  203. - **`mode`**: Either `"include"` (allow-list) or `"exclude"` (deny-list). Defaults to `"include"` if not specified.
  204. - **`tools`**: Array of exact tool names to include or exclude
  205. **Behavior:**
  206. - If `toolFilter` is not set or `tools` array is empty, all tools from the server are loaded (default behavior)
  207. - **Include mode** (allow-list): Only the tools listed in the `tools` array are made available. If a listed tool is not found on the server, a warning is logged but the server connection continues.
  208. - **Exclude mode** (deny-list): All tools except those listed in the `tools` array are made available. Listed tools are filtered out.
  209. - Tool names must match exactly (case-sensitive)
  210. - Invalid `mode` values cause the application to exit with an error message
  211. **Example with include mode (default):**
  212. ```json
  213. {
  214. "mcpServers": {
  215. "weather": {
  216. "command": "uv",
  217. "args": ["--directory", "./mock-weather-mcp-server", "run", "main.py"],
  218. "toolFilter": {
  219. "tools": ["get_current_temperature", "get_forecast"]
  220. }
  221. }
  222. }
  223. }
  224. ```
  225. **Example with explicit modes:**
  226. ```json
  227. {
  228. "mcpServers": {
  229. "weather": {
  230. "command": "uv",
  231. "args": ["--directory", "./mock-weather-mcp-server", "run", "main.py"],
  232. "toolFilter": {
  233. "mode": "include",
  234. "tools": ["get_current_temperature"]
  235. }
  236. },
  237. "filesystem": {
  238. "command": "npx",
  239. "args": ["-y", "@modelcontextprotocol/server-filesystem", "/tmp"],
  240. "toolFilter": {
  241. "mode": "exclude",
  242. "tools": ["delete_file", "write_file"]
  243. }
  244. }
  245. }
  246. }
  247. ```
  248. #### Variable Expansion
  249. The config also supports simple expansion in any string value:
  250. - `${workspaceFolder}` resolves to the directory containing the config file
  251. - `${env:VAR_NAME}` resolves to the corresponding environment variable
  252. Example:
  253. ```json
  254. {
  255. "mcpServers": {
  256. "filesystem": {
  257. "command": "npx",
  258. "args": [
  259. "-y",
  260. "@modelcontextprotocol/server-filesystem",
  261. "${workspaceFolder}/data"
  262. ]
  263. },
  264. "remote_with_headers": {
  265. "url": "https://example.com/mcp",
  266. "headers": {
  267. "X-Client-Name": "ollama-mcp-bridge",
  268. "X-Request-Tag": "${env:MCP_REQUEST_TAG}"
  269. }
  270. }
  271. }
  272. }
  273. ```
  274. > [!WARNING]
  275. > **Docker Command Limitations**: When running in Docker, MCP servers should use commands available in the container:
  276. > - ✅ `npx` for Node.js-based MCP servers
  277. > - ✅ `uvx` for Python-based MCP servers
  278. > - ✅ Direct executables in the container
  279. > - ❌ `docker` commands (unless Docker-in-Docker is configured)
  280. > - ❌ Local file paths from your host machine
  281. ### CORS Configuration
  282. Configure Cross-Origin Resource Sharing (CORS) to allow requests from your frontend applications:
  283. ```bash
  284. # Allow all origins (default, not recommended for production)
  285. ollama-mcp-bridge
  286. # Allow specific origins
  287. CORS_ORIGINS="http://localhost:3000,https://myapp.com" ollama-mcp-bridge
  288. # Allow multiple origins with different ports
  289. CORS_ORIGINS="http://localhost:3000,http://localhost:8080,https://app.example.com" ollama-mcp-bridge
  290. ```
  291. **CORS Logging:**
  292. - The bridge logs CORS configuration at startup
  293. - Shows warning when using `*` (all origins)
  294. - Shows allowed origins when properly configured
  295. > [!WARNING]
  296. > Using `CORS_ORIGINS="*"` allows all origins and is not recommended for production. Always specify exact origins for security.
  297. ### Environment Variables
  298. - `CORS_ORIGINS`: Comma-separated list of allowed origins (default: `*`)
  299. - `*` allows all origins (shows warning in logs)
  300. - Example: `CORS_ORIGINS="http://localhost:3000,https://myapp.com" ollama-mcp-bridge`
  301. - `MAX_TOOL_ROUNDS`: Maximum number of tool execution rounds (default: unlimited)
  302. - Can be overridden with `--max-tool-rounds` CLI parameter (CLI takes precedence)
  303. - Example: `MAX_TOOL_ROUNDS=5 ollama-mcp-bridge`
  304. - `OLLAMA_URL`: URL of the Ollama server (default: `http://localhost:11434`)
  305. - Can be overridden with `--ollama-url` CLI parameter
  306. - Useful for Docker deployments and configuration management
  307. - Example: `OLLAMA_URL=http://192.168.1.100:11434 ollama-mcp-bridge`
  308. - `UPSTREAM_HEADERS`: Optional JSON object of headers to send to the upstream server (e.g. for API key authentication)
  309. - These headers are not consumed by Ollama itself, but by whatever sits between the bridge and Ollama (reverse proxy / gateway / auth layer) — the upstream
  310. - Can be extended/overridden per-header with the repeatable `--upstream-header` CLI parameter (CLI takes precedence)
  311. - Useful for Docker deployments where headers shouldn't appear in the process list
  312. - Example: `UPSTREAM_HEADERS='{"Authorization": "Bearer token123", "X-API-Key": "secret"}' ollama-mcp-bridge`
  313. - `OLLAMA_PROXY_TIMEOUT`: Timeout for HTTP requests sent to Ollama, in **milliseconds** (default: unset)
  314. - When **unset**, the bridge keeps its existing behavior (some requests use library defaults; `/api/chat` is not timed out)
  315. - When set to a value **> 0**, the timeout is applied to Ollama-bound HTTP requests
  316. - When set to **0**, timeouts are disabled for Ollama HTTP requests (the bridge logs a warning)
  317. - Streaming chat responses always use no timeout, even when this variable is set
  318. - Example (10 minutes): `OLLAMA_PROXY_TIMEOUT=600000 ollama-mcp-bridge`
  319. - `SYSTEM_PROMPT`: Optional system prompt to prepend to all forwarded `/api/chat` requests
  320. - Can be set via the `SYSTEM_PROMPT` environment variable or `--system-prompt` CLI flag
  321. - 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.
  322. - Example: `SYSTEM_PROMPT="You are a concise assistant." ollama-mcp-bridge`
  323. ## Usage
  324. > [!NOTE]
  325. > An example MCP server script is provided at [mock-weather-mcp-server/main.py](mock-weather-mcp-server/main.py).
  326. ### Start the Server
  327. ```bash
  328. # Start with default settings (config: ./mcp-config.json, host: 0.0.0.0, port: 8000)
  329. ollama-mcp-bridge
  330. # Start with custom configuration file
  331. ollama-mcp-bridge --config /path/to/custom-config.json
  332. # Custom host and port
  333. ollama-mcp-bridge --host 0.0.0.0 --port 8080
  334. # Custom Ollama server URL (local or cloud)
  335. ollama-mcp-bridge --ollama-url http://192.168.1.100:11434
  336. # Send custom header(s) to the upstream server (repeatable, curl-style "Name: Value")
  337. ollama-mcp-bridge --upstream-header "X-API-Key: your-key"
  338. ollama-mcp-bridge --upstream-header "Authorization: Bearer xxx" --upstream-header "X-API-Key: yyy"
  339. # Keep the secret out of your shell history by letting the shell expand an env var
  340. ollama-mcp-bridge --upstream-header "Authorization: Bearer $MY_API_KEY"
  341. # Limit tool execution rounds (prevents excessive tool calls)
  342. ollama-mcp-bridge --max-tool-rounds 5
  343. # Set a system prompt to prepend to all /api/chat requests
  344. ollama-mcp-bridge --system-prompt "You are a concise assistant."
  345. # Combine options
  346. ollama-mcp-bridge --config custom.json --host 0.0.0.0 --port 8080 --ollama-url http://remote-ollama:11434 --max-tool-rounds 10
  347. # Combine options with an upstream API key header
  348. ollama-mcp-bridge --config custom.json --ollama-url http://remote-ollama:11434 --upstream-header "X-API-Key: your-key" --port 8080
  349. # Check version and available updates
  350. ollama-mcp-bridge --version
  351. ```
  352. > [!TIP]
  353. > If using `uvx` to run the bridge, you have to specify the command as `uvx ollama-mcp-bridge` instead of just `ollama-mcp-bridge`.
  354. > [!NOTE]
  355. > 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.
  356. ### CLI Options
  357. - `--config`: Path to MCP configuration file (default: `mcp-config.json`)
  358. - `--host`: Host to bind the server (default: `0.0.0.0`)
  359. - `--port`: Port to bind the server (default: `8000`)
  360. - `--ollama-url`: Ollama server URL (default: `http://localhost:11434`)
  361. - `--upstream-header`: Header to send to the upstream server as `"Name: Value"` (repeatable; can also be set via the `UPSTREAM_HEADERS` env var)
  362. - `--max-tool-rounds`: Maximum tool execution rounds (default: unlimited)
  363. - `--reload`: Enable auto-reload during development
  364. - `--version`: Show version information, check for updates and exit
  365. - `--system-prompt`: Optional system prompt to prepend to `/api/chat` requests (default: none)
  366. When configured, the custom upstream headers are added to bridge health checks and all requests that the bridge sends to the upstream server, including `/api/chat` and transparently proxied Ollama endpoints.
  367. ### API Usage
  368. The API is available at `http://localhost:8000`.
  369. - **Swagger UI docs:** [http://localhost:8000/docs](http://localhost:8000/docs)
  370. - **Ollama-compatible endpoints:**
  371. - `POST /api/chat` — Chat endpoint (same as Ollama API, but with MCP tool support)
  372. - **This is the only endpoint where MCP server tools are integrated.** All tool calls are handled and responses are merged transparently for the client.
  373. - **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.
  374. - **Bridge-specific endpoints:**
  375. - `GET /health` — Health check endpoint (not proxied)
  376. - `GET /version` — Version information and update check
  377. > [!IMPORTANT]
  378. > `/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.
  379. 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.
  380. ### Example: Chat
  381. ```bash
  382. curl -N -X POST http://localhost:8000/api/chat \
  383. -H "accept: application/json" \
  384. -H "Content-Type: application/json" \
  385. -d '{
  386. "model": "qwen3:0.6b",
  387. "messages": [
  388. {
  389. "role": "system",
  390. "content": "You are a weather assistant."
  391. },
  392. {
  393. "role": "user",
  394. "content": "What is the weather like in Paris today?"
  395. }
  396. ],
  397. "think": true,
  398. "stream": true,
  399. "options": {
  400. "temperature": 0.7,
  401. "top_p": 0.9
  402. }
  403. }'
  404. ```
  405. > [!TIP]
  406. > Use `/docs` for interactive API exploration and testing.
  407. ## Development
  408. ### Key Dependencies
  409. - **FastAPI**: Modern web framework for the API
  410. - **Typer**: CLI framework for command-line interface
  411. - **loguru**: Structured logging throughout the application
  412. - **ollama**: Python client for Ollama communication
  413. - **mcp**: Model Context Protocol client library
  414. - **pytest**: Testing framework for API validation
  415. ### Testing
  416. The project has two types of tests:
  417. #### Unit Tests (GitHub Actions compatible)
  418. ```bash
  419. # Install test dependencies
  420. uv sync --extra test
  421. # Run unit tests (no server required)
  422. uv run pytest tests/test_unit.py -v
  423. ```
  424. These tests check:
  425. - Configuration file loading
  426. - Module imports and initialization
  427. - Project structure
  428. - Tool definition formats
  429. #### Integration Tests (require running services)
  430. ```bash
  431. # First, start the server in one terminal
  432. ollama-mcp-bridge
  433. # Then in another terminal, run the integration tests
  434. uv run pytest tests/test_api.py -v
  435. ```
  436. These tests check:
  437. - API endpoints with real HTTP requests
  438. - End-to-end functionality with Ollama
  439. - Tool calling and response integration
  440. #### Manual Testing
  441. ```bash
  442. # Quick manual test with curl (server must be running)
  443. curl -X GET "http://localhost:8000/health"
  444. # Check version information and update status
  445. curl -X GET "http://localhost:8000/version"
  446. curl -X POST "http://localhost:8000/api/chat" \
  447. -H "Content-Type: application/json" \
  448. -d '{"model": "qwen3:0.6b", "messages": [{"role": "user", "content": "What tools are available?"}]}'
  449. ```
  450. > [!NOTE]
  451. > Tests require the server to be running on localhost:8000. Make sure to start the server before running pytest.
  452. ## Contributing
  453. We welcome contributions! Please see [CONTRIBUTING.md](CONTRIBUTING.md) for:
  454. - Development setup instructions
  455. - Code formatting guidelines (Black)
  456. - Testing procedures
  457. - Commit conventions
  458. ## Related Projects
  459. - [**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.
  460. - [**simple-ollama-chat**](https://github.com/jonigl/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.
  461. ## Inspiration and Credits
  462. 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).
  463. 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).
  464. ---
  465. Made with ❤️ by [jonigl](https://github.com/jonigl)

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.