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 server_info and list_models from Ollama Handoff. Confirm that the configured model is installed. Then call summarize_local with the following text, focusing on the failed test:

10:00:01 INFO Starting build
10:00:02 INFO Compiled 12 modules
10:00:03 ERROR tests/test_checkout.py::test_total 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

A successful run discovers 8 tools, lists your model, and returns the summary. Each call prints its elapsed time. Verified on Windows with Python 3.14, MCP 1.30.0, and llama3.1:8b. Timing is not a benchmark; the first model load may take longer.

Tools

Generated summaries and reviews need checking. The server does not read files, stage changes, or create commits for you.

Configuration

Set these variables in your MCP registration:

For a small task on a machine with limited memory, try OLLAMA_NUM_CTX=4096 and a smaller model.

The selected Ollama endpoint receives the text sent to these tools. A remote endpoint sends that text to another machine. Local execution does not prevent your calling client from sending prompts or results to its own cloud provider.

Troubleshooting

server_info checks configuration without contacting Ollama. list_models checks connectivity. A successful summarize_local call also confirms generation.

Docker

The included Dockerfile builds the source package. Keep stdin open for MCP:

docker build -t ollama-handoff .
docker run --rm -i -e OLLAMA_URL=http://host.docker.internal:11434 -e OLLAMA_DEFAULT_MODEL=llama3.1:8b ollama-handoff

On Linux without Docker Desktop, use --network=host with OLLAMA_URL=http://localhost:11434. Do not add -t when an MCP client launches the container.

Development

uv venv
uv pip install -e ".[dev]"
uv run --no-project ruff check .
uv run --no-project pytest

Unit tests use httpx.MockTransport and do not need Ollama. The demo uses real inference. See CONTRIBUTING.md.

License

MIT © Michael Tierney