ollama-mcp-delegate
The server is an MCP tool that delegates mechanical coding work to a local Ollama model while keeping Claude as the orchestrator, saving tokens by keeping file contents out of Claude's context.
local_edit: delegate well-specified edits (renames, docstrings, type annotations, boilerplate, formatting fixes) to the local model without reading files first; edits are gated, rolled back, or escalated if they fail verification.
local_explain: ask factual questions about the repo ("where is X defined", "what does module Y do") and get a dense answer with path:line citations instead of dumping file contents.
local_verify: run the project's verification gate (lint/typecheck/tests) and return PASS or a compact triage of failures, instead of raw tool output.
local_status: check Ollama health, installed model tiers, gate config, and estimated token savings so far.
It supports fast/deep model tiers, per-project configuration via
.ollama-mcp.toml, sandbox path restrictions, automatic rollback on failed gates, and Japanese/English prompting.
Delegates mechanical coding tasks to local Ollama models, enabling file edits, code lookups, verification, and status/metrics reporting with deterministic gate checks and rollback.
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-mcp-delegate add type annotations to src/utils.py, don't show me the file"
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.
ollama-mcp-delegate
日本語版: README.ja.md · 日本語環境での挙動
An MCP server that lets Claude Code stay the orchestrator while a local Ollama model does the mechanical work — file edits, code lookups, lint triage — so that text never enters Claude's context and you pay fewer tokens for the same result.
you ──▶ Claude Code (Anthropic) ← decides, plans, reviews
│
│ paths + instruction (small)
▼
ollama-mcp-delegate ──▶ Ollama ──▶ qwen2.5-coder / qwen3-coder
│ │
│ └── reads files, greps, edits — all locally
│
▼ verification gate (syntax + your project's checks)
│
│ receipt: files changed, +12/-4, gate=pass (small)
▼
Claude CodeThe one idea
Delegation must displace content, not add a hop. The tools take paths and an instruction, never file contents, and return a receipt, never code. If Claude has to read a file in order to write the delegation prompt, the tokens are already spent and you have saved nothing.
The second idea, which is what makes the output trustworthy: nothing is reported as success until it passes a deterministic gate. Parity with pure Claude Code doesn't come from the local model being clever — it comes from a narrow task plus a machine-checkable result, with automatic rollback and escalation when the check fails.
Related MCP server: claude-token-saver-mcp
What it is not
It does not replace Claude. Routing all of Claude Code at Ollama via
ANTHROPIC_BASE_URLis a different thing — that removes Claude rather than creating a hybrid.It is not a way to make Claude Code subagents run locally. Subagent
model:frontmatter accepts Anthropic tiers only; this is the supported seam instead.It will not help with architecture, debugging, or ambiguity. Expect roughly 30–60% savings on delegable classes and ~0% on the hard thinking. Anyone promising more is counting wrong.
Install
Requires Python 3.10+ and Ollama. ripgrep is used for search when present; there is a pure-Python fallback, which matters on Windows where rg often exists only inside Git Bash and not on the system PATH.
git clone https://github.com/Rikiza89/ollama_mcp
cd ollama_mcp
uv venv && uv pip install -e .
ollama pull qwen2.5-coder:7b # fast tier
ollama pull qwen3-coder:30b # deep tier (~18 GB)Register it with Claude Code, once, for all your projects:
claude mcp add -s user ollama-local -- /abs/path/to/ollama_mcp/.venv/bin/ollama-mcp
# Windows: ...\ollama_mcp\.venv\Scripts\ollama-mcp.exeThen allow it without a prompt per call — in ~/.claude/settings.json:
{
"permissions": {
"allow": [
"mcp__ollama-local__local_edit",
"mcp__ollama-local__local_explain",
"mcp__ollama-local__local_verify",
"mcp__ollama-local__local_status"
]
}
}Without this you get an approval prompt on every delegation and you will stop using it by day three.
Make Claude actually delegate
This is the step people skip, and it is the one that decides whether any of this pays off. Left alone, Claude will use its own Edit tool — it's faster and more certain from where it sits. You have to tell it not to. Add to your project's CLAUDE.md:
## Local delegation policy
A local model is available via the `ollama-local` MCP server. Route work to it.
DELEGATE to `local_edit` (do not Read the file first):
- docstrings, comments, translations of comments
- type annotations, renames, signature changes you have already decided on
- boilerplate, test scaffolding, applying a pattern across files
- formatting and lint fixes
DELEGATE to `local_explain` instead of Read/Grep when you need a fact, not the file:
- "where is X defined", "what does module Y do", "which call sites pass Z"
DELEGATE to `local_verify` instead of running lint/typecheck through Bash.
KEEP for yourself:
- architecture and design decisions
- debugging, root-cause analysis, anything ambiguous
- cross-file reasoning, security-sensitive code
- any edit where you cannot state the exact change in one paragraph
If a tool returns ESCALATE, the working tree is unchanged — do it yourself.Configure the gate
Drop a .ollama-mcp.toml in each project root. Only [gate] really matters; everything else has a working default.
[gate]
commands = [
["ruff", "check", "--quiet", "."],
["python", "-m", "pytest", "-x", "-q", "tests/unit"],
]
timeout_s = 180
[models]
fast = "qwen2.5-coder:7b"
deep = "qwen3-coder:30b"
fast_num_ctx = 16384
deep_num_ctx = 32768
keep_alive = "10m"
[limits]
max_iterations = 12
request_timeout_s = 900
max_local_retries = 1
[sandbox]
deny = [".git", ".env", "node_modules", ".venv", ".pem"]
[i18n]
language = "auto" # "auto" | "en" | "ja"The config file is validated when it loads: an unknown key, a value of the
wrong type, or a malformed commands entry stops the server with the file and
the key named, rather than silently falling back to a default three delegations
later. commands in particular is a list of argv lists — [["ruff", "check", "."]], not ["ruff check ."] — and the flat spelling is rejected rather than
quietly run one character at a time.
A gate command that cannot be executed at all — a typo, or a tool missing from
the PATH the MCP server was launched with, which is often not the PATH your
shell has — is reported as UNVERIFIED and fails the gate. A check that did
not run has not passed, and the gate is the whole basis for trusting a delegated
edit.
With no config file, the gate falls back to syntax checks on touched files plus an autodetected project check (ruff, tsc --noEmit, cargo check, go build).
Keep the gate fast. It runs after every delegated edit, and on failure it runs again after one local retry.
Language
[i18n] language (or OLLAMA_MCP_LANG) picks the language of the prompt sent to
the local model and of the prose in the receipt. auto, the default, decides per
call from the text of the instruction, falling back to the machine locale — so a
task written in Japanese gets the Japanese prompt on an English-locale laptop,
which is the common case.
Status tokens are never translated. APPLIED, NOT APPLIED, ESCALATE,
PASS and FAIL are protocol: every CLAUDE.md delegation policy in the wild
says "a tool returning ESCALATE means the working tree is unchanged", and a
localized token would quietly break all of them. Only the sentences around them
change.
Working in Japanese also changes a handful of things you would otherwise have to discover the hard way — non-UTF-8 consoles, BOMs, decomposed filenames, and what a token actually costs in CJK. See docs/ja/japanese-environment.md.
Tools
Tool | Use instead of | Returns |
| Read + Edit | files changed, |
| Read + Grep | a dense answer with |
| Bash lint/typecheck | PASS, or a triaged failure list |
| — | health, models installed, savings so far |
Four tools, deliberately. Every tool schema is re-sent on every request forever; a twelve-tool belt eats back the savings it exists to create.
Local models that ignore the tool-calling channel
Ollama advertises a tools capability for any model whose template can render tool schemas — but plenty of them, qwen2.5-coder included, print the call into the message body instead: as bare JSON, in a ```json fence, or wrapped in <tool_call> tags. Untreated this looks exactly like "the model finished without doing anything", which is the wrong diagnosis and produces a needless escalation.
So the server parses the message body as a fallback whenever the native field is empty, gated on the tool name being one it actually offers — a model quoting a config file does not get executed. If a model reports DONE without ever calling a write tool, it gets one pointed correction before the task escalates.
Does it actually save anything?
Every call appends a row to .ollama-mcp/metrics.jsonl in the project. local_status summarizes it:
savings so far: {"calls": 41, "succeeded": 34, "escalated": 7,
"estimated_tokens_avoided": 118400,
"tokens_spent_on_receipts": 4900,
"median_duration_s": 22.4}estimated_tokens_avoided is exactly that — an estimate, chars/4 of the file text the local model read that Claude therefore didn't. Treat it as a trend line, not an invoice. The honest check is the escalation rate: if more than about a third of delegations escalate, you are delegating the wrong class of work.
Hardware notes
qwen3-coder:30b is MoE (30B total, ~3B active), ~18 GB at Q4_K_M. That matters: unlike a dense 30B, it stays usable when most layers sit in system RAM. qwen2.5-coder:7b (4.7 GB) fits entirely in 8 GB VRAM with a 16k context — which is why the fast tier is the default and the deep tier is opt-in per call.
Measured on an RTX 5050 Laptop (8 GB VRAM) + Ryzen 7 260 + 32 GB RAM, adding Google-style docstrings to a 4-function module:
fast ( | deep ( | |
docstring edit | failed the gate, rolled back, escalated | applied, +37/−0, gate pass |
time | 39 s | 61 s cold, 26 s warm |
repo Q&A ( | correct, 3 s | — |
That first row is the design working, not the design failing: a 7B is not reliable at multi-site exact-string edits, the syntax gate caught its broken output, and the working tree was restored byte-for-byte. Use the fast tier for lookups and single-site edits; reach for tier="deep" as soon as an edit touches several places.
Don't keep both models resident. keep_alive pins the last one used; that's 18 GB of RAM for the deep tier.
Note on num_ctx: Ollama defaults to 4096 and truncates silently past it. This server always sends num_ctx explicitly. If you set it higher, remember the KV cache competes with model weights for VRAM.
Safety
The local model writes to your real working tree. Guards, in order:
Every path is resolved and confined to
workspace_root; traversal is rejected.[sandbox] denyblocks.git,.env, keys,node_modules, and anything else you list. One rule set governs every route to a file's contents —read_file,grepandlist_filesalike — so search cannot return whatread_filerefuses to open.Original file contents are snapshotted in memory before the first write and restored automatically if the gate fails.
local_explainandlocal_verifyrun with no write tools at all.Edits preserve each file's existing line endings and byte content — no whole-file CRLF churn, and non-ASCII comments (Japanese, accented text) survive a non-UTF-8 console, a BOM, or a legacy Shift-JIS encoding.
The local model's transcript is held to a fraction of
num_ctx, with the oldest tool results dropped when it would overflow. Ollama truncates an over-long prompt silently, and a model that edits a file it only half saw is the failure this design most needs not to have.
Run it in a git repository anyway. In-memory rollback covers gate failures; it does not cover a model that succeeded at the wrong thing.
.ollama-mcp.toml is executable configuration
[gate] commands are commands this server runs in your working tree. A repository you clone carries its own, so local_verify — and the gate that follows every local_edit — will run whatever that file says. This is the same trust model as .vscode/tasks.json or a Makefile, and it deserves the same habit: read a new repository's .ollama-mcp.toml before delegating into it.
Development
uv pip install -e ".[dev]"
pytest # 173 tests against a fake Ollama fixture — no GPU, no models needed
ruff check .License
MIT
Available Tools
4 toolslocal_editA
Delegate a MECHANICAL code edit to the local model. USE THIS INSTEAD OF Read+Edit whenever the change is well-specified and does not need cross-file reasoning: renames, docstrings and comments, type annotations, adding a logging line, applying a pattern you already decided on, boilerplate, test scaffolding, formatting fixes.
Do NOT read the files first -- that spends the tokens this tool exists to save.
Pass file paths inside instruction and let the local model read them.
The edit is applied to the working tree only if it passes the project's verification gate; otherwise it is rolled back and you get an ESCALATE.
Args: workspace_root: Absolute path to the repository root. instruction: Self-contained task, naming the exact files and the exact change. The local model sees nothing else -- no conversation history. tier: "fast" for mechanical/high-volume work, "deep" for edits needing real code reasoning (slower, larger model).
Returns: A receipt: files changed with line counts, gate verdict, timing. Never file content.
Inputs: instruction (required), workspace_root (required), tier. Returns: result
local_explainA
Ask the local model to read the repository and answer a FACTUAL question about it. USE THIS INSTEAD OF Read/Grep when you need to know what is in files but do not need the files themselves in context: "where is X defined", "what does module Y do", "which call sites pass argument Z", "summarize this log".
Read-only: the local model has no write tools for this call.
Args: workspace_root: Absolute path to the repository root. question: A specific, answerable question. Vague questions get ESCALATE. tier: "fast" (default) or "deep" for multi-file reasoning. answer_budget: Soft character cap on the answer. Keep it small.
Returns: A dense answer with path:line citations, or ESCALATE. Never file dumps.
Inputs: question (required), workspace_root (required), tier, answer_budget. Returns: result
local_statusA
Check that local delegation is actually available and see what it has saved. Cheap -- no model inference. Call this once at the start of a session if you intend to delegate, and whenever a local tool fails unexpectedly.
Args: workspace_root: Absolute path to the repository root.
Returns: Ollama health, configured model tiers, whether they are installed, the gate configuration, and estimated tokens avoided so far.
Inputs: workspace_root (required). Returns: result
local_verifyA
Run this project's verification gate (from .ollama-mcp.toml, or autodetected) and return a COMPACT triage of any failures. USE THIS INSTEAD OF running lint/typecheck/test commands through Bash when you only need to know whether it passes and what broke -- raw tool output is often thousands of tokens.
Args: workspace_root: Absolute path to the repository root. triage: If true and the gate fails, the local model summarizes the failures into a short actionable list instead of returning raw output.
Returns: PASS, or a short list of what failed and where.
Inputs: workspace_root (required), triage. Returns: result
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 4 tools
Each tool targets a distinct operation: edit (write), explain (read-only query), verify (gate runner), and status (health check). The descriptions explicitly delineate when to use each and even contrast them against native Read/Edit/Bash, leaving no meaningful overlap.
All four tools follow a strict local_<verb> pattern (local_edit, local_explain, local_verify, local_status). The convention is predictable and unambiguous throughout.
Four tools is well-scoped for a delegation server, and each one earns its place covering a distinct phase of the delegate workflow. No redundancy or filler.
The surface covers the core delegation lifecycle: availability check, read-only queries, edits, and verification. Minor gaps exist (e.g. no explicit undo/rollback or batch-edit operation), but agents can work around these.
Related MCP Connectors
Work on your own computers from Claude or ChatGPT: run commands, edit and search files.
Operate Linux, macOS and Windows from your LLM. Every action runs through an auditable allowlist.
Use your Mac, Windows or Linux computer from ChatGPT, Claude or Codex: files, commands, documents.
Your AI agent is smart enough to code all day. Local firewall & zero-loss runtime.
Related MCP Servers
- AlicenseNot gradedqualityDmaintenanceEnables Claude to delegate coding tasks to local Ollama models, reducing API token usage by up to 98.75% while leveraging local compute resources. Supports code generation, review, refactoring, and file analysis with Claude providing oversight and quality assurance.27AGPL 3.0
- AlicenseAqualityDmaintenanceEnables Claude Code to offload routine code generation and text processing tasks to a local Ollama LLM, saving Cloud API tokens and costs with automatic model selection and security features.11372 npm3Apache 2.0
- AlicenseNot gradedqualityBmaintenanceEnables Claude Code to hand off bulk, mechanical, read-heavy tasks to a local model, including agentic loops that can read, write, and run commands sandboxed at zero cloud token cost.MIT
- AlicenseNot gradedqualityBmaintenanceEnables a cloud coding agent to delegate a focused coding task to a local Ollama or OpenAI-compatible model through a bounded workspace, file allowlist, and required external checks. Changes are applied only after verification against the declared scope, with failed post-apply checks rolled back and the rollback itself confirmed.66 PyPI11MIT