Ollama Handoff MCP server

<!-- mcp-name: io.github.Michael-WhiteCapData/ollama-handoff -->

Ollama Handoff

Local summaries, extractions, code reviews, and commit drafts for your MCP client.

Ollama Handoff lets your agent send routine text tasks to a model running on your machine. Eight MCP tools provide focused prompts, model discovery, and configuration checks.

Local inference does not incur cloud model API charges. Your calling agent can still use paid tokens to plan tasks and read results. Speed, memory use, and quality depend on your model and hardware.

Quick start

1. Prepare Ollama

Install Ollama and uv. Python 3.11 or newer is required; uv can manage Python for you.

ollama pull llama3.1:8b
ollama list

Keep Ollama running. If the desktop app or service is not already running, start ollama serve in another terminal.

These examples select llama3.1:8b. You can substitute another installed model. Without an override, the package defaults to qwen2.5-coder:14b, which must be downloaded separately.

2. Register the server

For Claude Code:

claude mcp add --transport stdio --env OLLAMA_DEFAULT_MODEL=llama3.1:8b ollama-handoff -- uvx ollama-handoff@0.1.3

For a client that accepts an mcpServers JSON configuration:

{
  "mcpServers": {
    "ollama-handoff": {
      "command": "uvx",
      "args": ["ollama-handoff@0.1.3"],
      "env": {
        "OLLAMA_DEFAULT_MODEL": "llama3.1:8b"
      }
    }
  }
}

Add this entry using your client's MCP settings, then reconnect or restart it. If the client cannot find uvx, use the absolute path reported by where.exe uvx on Windows or command -v uvx on macOS and Linux.

Version 0.1.3 declares the MCP compatibility constraint automatically. This server uses the MCP 1 FastMCP API, which MCP 2 removed. If you remain on version 0.1.2, add --with "mcp<2" to the uvx command.

For pip, install into a virtual environment and configure your client to run that environment's ollama-handoff executable:

python -m pip install "ollama-handoff==0.1.3"

3. Verify the connection

Ask your agent:

Call serverinfo and listmodels from Ollama Handoff. Confirm that the configured model is installed. Then call summarize_local with the following text, focusing on the failed test:

text

10:00:01 INFO Starting build

10:00:02 INFO Compiled 12 modules

10:00:03 ERROR tests/testcheckout.py::testtotal expected 42.00, got 40.00

10:00:03 ERROR Build stopped because one test failed

Check that the summary identifies test_total, the expected total of 42.00, and the actual total of 40.00. Wording varies by model. Tools accept text, not file paths: your agent must supply file contents when needed.

Run the demo without an agent

The demo launches the real MCP server over stdio, discovers its tools, checks configuration, lists installed models, and summarizes the synthetic log above. It requires local Ollama but no cloud API key.

git clone https://github.com/Michael-WhiteCapData/ollama-handoff.git
cd ollama-handoff
uv venv
uv pip install -e .
uv run --no-project python examples/demo.py --model llama3.1:8b

Shortened. The full README is on GitHub.