{
  "markdown": "<!-- mcp-name: io.github.Michael-WhiteCapData/ollama-handoff -->\n\n# ollama-handoff\n\n**An MCP server that offloads cheap work from your cloud LLM agent to a local Ollama model.**\n\n[![CI](https://github.com/Michael-WhiteCapData/ollama-handoff/actions/workflows/ci.yml/badge.svg)](https://github.com/Michael-WhiteCapData/ollama-handoff/actions/workflows/ci.yml)\n[![PyPI](https://img.shields.io/pypi/v/ollama-handoff?color=3775A9&logo=pypi&logoColor=white)](https://pypi.org/project/ollama-handoff/)\n[![Python](https://img.shields.io/badge/python-3.11%2B-3776AB?logo=python&logoColor=white)](https://www.python.org/)\n[![MCP](https://img.shields.io/badge/MCP-server-D97757)](https://modelcontextprotocol.io/)\n[![License: MIT](https://img.shields.io/badge/License-MIT-green.svg)](LICENSE)\n\nYour frontier model (Claude, GPT, etc.) is brilliant and metered. A lot of the work it gets handed — summarizing a log, drafting a commit message, pulling every URL out of a file, a quick first-pass code review — **doesn't need frontier reasoning at all.** `ollama-handoff` exposes your local [Ollama](https://ollama.com/) instance as a handful of purpose-built [MCP](https://modelcontextprotocol.io/) tools, so your agent can route that work to a model on **your own GPU** — at **zero cloud cost** — and spend its (paid) reasoning budget on the things that actually need it.\n\nThis isn't a generic \"wrap the Ollama API\" server. Each tool ships with a **baked-in system prompt** and a **description written for the calling agent**, so the agent knows *when* to hand off and gets a tuned result back without re-stating instructions every call.\n\n---\n\n## Why you'd want this\n\n- 💸 **Spend less.** Routine offloads run locally and bill nothing.\n- ⚡ **Keep the big model focused.** Summaries, extractions, and drafts don't eat its context or your budget.\n- 🧠 **Tuned, not raw.** `summarize_local`, `code_review_local`, `draft_commit_message_local`, and `extract_local` come with reviewer/summarizer/extractor system prompts already dialed in.\n- 🔌 **Drop-in.** One MCP registration; works with Claude Code, Claude Desktop, Cursor, and any MCP client.\n- 🪶 **Tiny & auditable.** Two dependencies (`mcp`, `httpx`), fully typed, unit-tested, no telemetry.\n\n## Requirements\n\n- [Ollama](https://ollama.com/) running locally (`ollama serve`) with at least one model pulled, e.g. `ollama pull qwen2.5-coder:14b`.\n- Python 3.11+ (or just `uvx`, which manages it for you).\n\n## Install\n\nThe fastest path is [`uv`](https://docs.astral.sh/uv/) — no manual venv needed:\n\n```bash\nuvx ollama-handoff          # run directly\n# or\npip install ollama-handoff  # then run: ollama-handoff\n```\n\n### Claude Code\n\n```bash\nclaude mcp add ollama-handoff -- uvx ollama-handoff\n```\n\n### Claude Desktop / Cursor (`mcp` config block)\n\n```jsonc\n{\n  \"mcpServers\": {\n    \"ollama-handoff\": {\n      \"command\": \"uvx\",\n      \"args\": [\"ollama-handoff\"],\n      \"env\": {\n        \"OLLAMA_DEFAULT_MODEL\": \"qwen2.5-coder:14b\"\n      }\n    }\n  }\n}\n```\n\n## Run with Docker\n\nA [`Dockerfile`](Dockerfile) is included. The server speaks MCP over stdio, so run it\ninteractively (`-i`) and point it at your Ollama instance:\n\n```bash\ndocker build -t ollama-handoff .\ndocker run --rm -i -e OLLAMA_URL=http://host.docker.internal:11434 ollama-handoff\n```\n\nOn native Linux (no Docker Desktop), use `--network=host` with\n`OLLAMA_URL=http://localhost:11434`.\n\n## Tools\n\n| Tool | What it does | When the agent should reach for it |\n| --- | --- | --- |\n| `ask_local` | One-shot prompt to the local model | Any handoff that doesn't need frontier reasoning |\n| `chat_local` | Multi-turn local chat | Handoffs needing more than one turn of context |\n| `summarize_local` | Structured summary (headline + bullets) | Long files, logs, transcripts, docs |\n| `code_review_local` | Quick first-pass review of a diff/code | Cheap pre-filter before a deep review |\n| `draft_commit_message_local` | Conventional commit message from a diff | Routine commits |\n| `extract_local` | Pull structured items from unstructured text | URLs, function names, error codes, TODOs |\n| `list_models` | List locally available Ollama models | Discovery / choosing a model |\n| `server_info` | Report the effective configuration | Debugging setup |\n\n## Configuration\n\nAll configuration is via environment variables set in your MCP registration:\n\n| Variable | Default | Description |\n| --- | --- | --- |\n| `OLLAMA_URL` | `http://localhost:11434` | Base URL of the Ollama server |\n| `OLLAMA_DEFAULT_MODEL` | `qwen2.5-coder:14b` | Default model for handoffs |\n| `OLLAMA_NUM_CTX` | `32768` | Context window in tokens |\n| `OLLAMA_KEEP_ALIVE` | `30m` | How long to keep the model resident in VRAM |\n| `OLLAMA_TIMEOUT_S` | `600` | Per-request timeout, seconds |\n\n## Example\n\nOnce registered, you don't call the tools yourself — your agent does. A typical exchange:\n\n> **You:** Summarize the errors in `build.log` and draft a commit for the staged fix.\n>\n> **Agent:** *(calls `summarize_local(build.log, focus=\"errors and stack traces\")` and `draft_commit_message_local(git diff --staged)` — both run on your GPU, nothing billed)* → returns the summary + commit message.\n\n## Development\n\n```bash\ngit clone https://github.com/Michael-WhiteCapData/ollama-handoff\ncd ollama-handoff\nuv pip install -e \".[dev]\"\nruff check .\npytest          # tests use httpx.MockTransport — no running Ollama required\n```\n\nSee [CONTRIBUTING.md](CONTRIBUTING.md). Contributions welcome — especially new specialized handoff tools.\n\n## License\n\n[MIT](LICENSE) © Michael Tierney\n",
  "bytes": 5535,
  "sha": "5c4bbb5a25d4771e0e0dc0be1d0cc347b370bdcee797085c7e91c864fd3cd0a4",
  "repo_slug": "michael-whitecapdata/ollama-handoff",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_michael_whitecapdata_ollama_ha_870823a7/readme"
}