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.
日本語版: 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 CodeDelegation 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
It does not replace Claude. Routing all of Claude Code at Ollama via ANTHROPIC_BASE_URL is 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.
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.
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.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 or a value of the wrong type stops the server with the file and the key named, rather than silently falling back to a default three delegations later.
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.
[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.
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.
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.
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.
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.
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] deny blocks .git, .env, keys, node_modules, and anything else you list.
Original file contents are snapshotted in memory before the first write and restored automatically if the gate fails.
local_explain and local_verify run 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.
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.
uv pip install -e ".[dev]"
pytest # 128 tests against a fake Ollama fixture — no GPU, no models needed
ruff check .MIT
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.
| Name | Required | Description | Default |
|---|---|---|---|
| tier | No | fast | |
| instruction | Yes | ||
| workspace_root | Yes |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden and does so: edits apply to the working tree only if they pass a verification gate, otherwise they are rolled back and an ESCALATE is returned, and the response is a receipt with no file content. This discloses mutation semantics, failure behavior, and return shape that the schema does not.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Front-loaded purpose, then clearly delimited USE / DO NOT / Args / Returns blocks, so an agent can scan it quickly. Slightly long, and the Returns block partially restates the output schema, though the 'Never file content' note still adds value.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
An output schema exists, yet the description still summarizes the return as a receipt rather than file content, which is exactly the disambiguation an agent needs. Combined with tier guidance and the escalation path, nothing required to invoke this correctly is missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0%, so the description must compensate and does: `workspace_root` is an absolute repo-root path, `instruction` must be self-contained because the local model sees no conversation history, and `tier` maps 'fast' to mechanical/high-volume vs 'deep' to reasoning-heavy edits. Every parameter gains meaning beyond the bare schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb and resource — 'Delegate a MECHANICAL code edit to the local model' — and immediately contrasts it with the Read+Edit path an agent would otherwise use. The scope qualifier 'mechanical' plus the enumerated change types make the purpose unambiguous without opening the schema.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicit when-to-use (renames, docstrings, type annotations, logging lines, boilerplate, formatting), an explicit negative constraint ('Do NOT read the files first'), and a boundary condition (no cross-file reasoning needed). It even tells the agent how to route: pass paths inside `instruction`.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
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.
| Name | Required | Description | Default |
|---|---|---|---|
| tier | No | fast | |
| question | Yes | ||
| answer_budget | No | ||
| workspace_root | Yes |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full behavioral burden and does so well: it discloses the read-only/no-write-tools guarantee, the ESCALATE outcome for vague questions, the output shape (dense answer with path:line citations, never file dumps), and the tier/answer_budget trade-off. These are traits an agent could not infer from the schema.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Front-loaded with a clear Args/Returns structure, and every subsection earns its place. The opening sentence is somewhat long and the quoted example questions add length, but no content is filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a four-parameter read tool with no annotations, the definition is complete: purpose, routing against alternatives, mode selection, budget control, and the escalation/failure mode are all covered. The return-value note is brief and appropriate given an output schema exists.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must compensate, and it documents all four parameters: workspace_root (absolute repo root), question (must be specific or it ESCALATEs), tier ('fast' default, 'deep' for multi-file reasoning), and answer_budget (soft character cap, keep small). Each adds meaning beyond the bare schema titles.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description gives a precise verb+resource: 'Ask the local model to read the repository and answer a FACTUAL question about it,' with concrete sample questions. It also implicitly separates itself from the write-oriented sibling local_edit via 'Read-only: the local model has no write tools.' It stops short of naming its actual siblings (local_verify, local_status), so differentiation from those is left to inference.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
It explicitly states when to use 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') and names the condition that selects the alternative (when you do need the files in context). Both the positive trigger and the exclusions are spelled out.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
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.
| Name | Required | Description | Default |
|---|---|---|---|
| workspace_root | Yes |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden and does well: it discloses the cost profile ('Cheap -- no model inference') and enumerates what the call reports. It does not mention auth, rate limits, or failure modes of the probe itself, so a small gap remains.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Front-loaded purpose sentence followed by a cheapness note, then labeled Args/Returns. Structure is clean and every line earns its place, though the Args/Returns block is slightly redundant given the schema and output schema already exist.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a single-parameter status tool with an output schema already present, the description is complete: it explains purpose, timing, cost, the parameter, and the shape of the result. Nothing an agent needs to invoke it correctly is missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0%, so the description must compensate, and it does with 'workspace_root: Absolute path to the repository root.' That adds the format/semantics (absolute path) the schema lacks, though it is the only parameter and needs little elaboration.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description gives a specific verb+resource ('Check that local delegation is actually available and see what it has saved'), so the agent knows this is a status/health probe rather than an action. It does not explicitly contrast itself with the siblings local_edit, local_explain, and local_verify, relying on the name to differentiate.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
It states exactly when to call it: 'once at the start of a session if you intend to delegate, and whenever a local tool fails unexpectedly.' This is explicit when-to-use guidance with a triggering condition, leaving nothing to inference.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
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.
| Name | Required | Description | Default |
|---|---|---|---|
| triage | No | ||
| workspace_root | Yes |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries full burden. It discloses that raw tool output is often thousands of tokens and that triage summarizes failures via a local model, and it describes the return shape (PASS or short failure list). It does not disclose anything about side effects, permissions, or runtime characteristics like duration, but the core behavior is transparent.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is front-loaded with purpose and the Bash replacement rationale, then structured sections for Args and Returns, which is easy to scan. It is slightly verbose in the Args/Returns blocks, but every sentence contributes information an agent needs.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With an output schema present, return-value detail is optional, yet the description also summarizes the return form (PASS or short failure list), which is sufficient. Combined with parameter meanings and the use-instead-of-Bash guidance, an agent has everything needed to invoke it correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must compensate. It documents both parameters: workspace_root as an absolute repository path, and triage as a boolean that, when true and the gate fails, produces a local-model summary. This adds meaning well beyond the bare schema types and default.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description names a specific action (run this project's verification gate) and specifies the source config (.ollama-mcp.toml or autodetected), and even names the exact alternative it replaces (Bash lint/typecheck/test). An agent can distinguish it from local_edit, local_explain, and local_status without opening any schema.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
It explicitly states when to use it: instead of running lint/typecheck/test through Bash when you only need to know pass/fail and what broke. The condition 'when you only need to know whether it passes and what broke' is a clear when-to-use criterion with a named alternative.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
v0.2.0local_editlocal_explainlocal_statuslocal_verifyScored 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.
Operate Linux, macOS and Windows from your LLM. Every action runs through an auditable allowlist.
Your coding agent tells a coworker's agent what you found or changed. Invite-only.
No-data MCP handoff for local Claude Code to Codex harness moves. $49 lifetime.
A paid remote MCP for OpenAI Codex agent coordination MCP, built to return verdicts, receipts, usage
