This server lets an MCP client offload routine text tasks to a local Ollama model for summaries, code reviews, commit drafts, extraction, and chat without cloud API charges.
ask_local: Send a one-shot prompt with optional system instruction.
chat_local: Run a multi-turn conversation with explicit message history.
summarize_local: Summarize supplied text, optionally focused on a topic.
code_review_local: Get a first-pass review of code or a diff.
draft_commit_message_local: Generate a conventional-style commit message from a diff.
extract_local: Pull structured items like URLs, names, or error codes from text.
list_models: Discover installed Ollama models.
server_info: Inspect effective configuration (model, context size, etc.).
Works with configurable Ollama URL, default model, context window, keep-alive, and timeout.
Local execution avoids cloud model API charges, though results should be checked.
Enables AI agents to offload routine tasks to local Ollama models, reducing cloud costs and frontier model context usage.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type @ followed by the MCP server name and your instructions, e.g., "@ollama-handoff summarize the errors in build.log"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
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.
Install Ollama and uv. Python 3.11 or newer is required; uv can manage Python for you.
ollama pull llama3.1:8b
ollama listKeep 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.
For Claude Code:
claude mcp add --transport stdio --env OLLAMA_DEFAULT_MODEL=llama3.1:8b ollama-handoff -- uvx ollama-handoff@0.1.3For 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"Ask your agent:
Call
server_infoandlist_modelsfrom Ollama Handoff. Confirm that the configured model is installed. Then callsummarize_localwith 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.
Related MCP server: local-llm-delegation-mcp
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:8bA 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.
Tool | Use it for |
| A single prompt with an optional system instruction |
| A conversation with explicit message history |
| Summaries of supplied text, optionally focused on a topic |
| Initial review of supplied code or a diff |
| A commit message from a supplied diff |
| Extracting items such as URLs, names, or error codes |
| Discovering installed Ollama models |
| Inspecting effective server configuration |
Generated summaries and reviews need checking. The server does not read files, stage changes, or create commits for you.
Set these variables in your MCP registration:
Variable | Default | Description |
|
| Ollama server URL |
|
| Model used when a tool call omits a model |
|
| Context window in tokens |
|
| Time to keep the model loaded |
|
| Generation and chat request timeout in seconds |
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.
Symptom | What to check |
| Upgrade to version 0.1.3 and restart the MCP client |
| Restart the client after installing uv, or configure the absolute executable path |
Connection refused | Confirm Ollama is running and |
Model not found | Match the full name from |
Slow response or timeout | Allow for model loading; try a smaller model or context |
Server appears idle in a terminal | This stdio server waits for an MCP client; it is not an interactive chat CLI |
server_info checks configuration without contacting Ollama. list_models checks connectivity. A successful summarize_local call also confirms generation.
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-handoffOn Linux without Docker Desktop, use --network=host with OLLAMA_URL=http://localhost:11434. Do not add -t when an MCP client launches the container.
uv venv
uv pip install -e ".[dev]"
uv run --no-project ruff check .
uv run --no-project pytestUnit tests use httpx.MockTransport and do not need Ollama. The demo uses real inference. See CONTRIBUTING.md.
MIT © Michael Tierney
Send a one-shot prompt to a local Ollama model and return its text response.
Use for any handoff where the cloud model's full reasoning isn't needed: drafts, boilerplate, simple extractions, formatting, or quick lookups. Runs on the user's own GPU and consumes no cloud-LLM usage. Returns the model's raw text completion.
Inputs: prompt (required), model, system. Returns: result
Hold a multi-turn chat against a local Ollama model.
Use instead of ask_local when the handoff needs more than one turn of
context — a running conversation or a system + user + assistant history.
Runs locally at no cloud cost. Returns the model's next assistant message
as text.
Inputs: messages (required), model. Returns: result
Run a quick first-pass code review using the local coder model.
Use as a cheap pre-filter before asking the cloud model for a deeper review: it catches obvious bugs, style issues, and risky patterns. Runs locally at no cloud cost. Returns review notes as text.
Inputs: diff_or_code (required), model. Returns: result
Draft a conventional-style commit message from a diff using the local model.
Use for routine commits where the cloud model's analysis isn't needed — it is cheap and fast. Runs locally at no cloud cost. Returns a single commit message (subject plus optional body) as text.
Inputs: diff (required), model. Returns: result
Extract specific information from a text block using the local model.
Use to pull structured facts out of unstructured text — function names, URLs,
error codes, TODO comments, dependency names — without spending cloud-model
tokens. Runs locally at no cloud cost. Returns the extracted items as text,
shaped by what_to_extract.
Inputs: text (required), what_to_extract (required), model. Returns: result
List the Ollama models installed locally and available to these tools.
Use to discover valid values for the model parameter before pinning a
specific model. Returns a list of model-name strings.
Inputs: no named parameters. Returns: result
Report the server's effective configuration.
Returns the default model, Ollama base URL, context size, and request timeout. Use to confirm which model the tools will use by default or to debug connectivity. Returns a JSON object.
Inputs: no named parameters.
Summarize a block of text using the local model.
Use to offload long files, logs, transcripts, or docs the cloud model does
not need to fully ingest — call this instead of reading a large blob into the
cloud context. Runs on the user's GPU at no cloud cost. Returns a concise
prose summary; pass focus to bias it toward what matters.
Inputs: text (required), focus, model. Returns: result
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
Scored across 8 tools
Each task-specific tool (summarize, code_review, draft_commit_message, extract) has a clear purpose, and ask_local vs chat_local cleanly separate one-shot from multi-turn. The main overlap is that ask_local is framed as a catch-all ('simple extractions, formatting'), which could lead an agent to use it instead of the more specialized extract or code_review tools.
Most operational tools follow a verb_object_local pattern (ask_local, chat_local, summarize_local, extract_local), and all names use snake_case. Deviations include code_review_local and server_info, which don't fit the verb-object shape, and list_models/server_info lack the _local suffix.
Eight tools is well-scoped: six local-model task tools plus two discovery/config tools. Each tool has a distinct role with no obvious redundancy or missing foundational piece.
The set covers generic one-shot generation, multi-turn chat, summarization, extraction, code review, commit messages, model listing, and server config—strong coverage for a local handoff server. It lacks more advanced Ollama operations like streaming, model management, or embeddings, but those appear outside the declared handoff purpose.
Reduce your AI bills by up to 99% locally: focused code, warm prompt caches & zero secret leaks.
Multi-agent coordination outside your LLM context: dedupe parallel work, per-agent budgets, handoff
Cost-optimized LLM model routing recommendations for autonomous AI agents
Memory, reflection and safety for AI agents. Hosted or local, no vector database.