Skip to main content
Glama

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 Code

The 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_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.

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.exe

Then 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

local_edit

Read + Edit

files changed, +n/-m, gate verdict

local_explain

Read + Grep

a dense answer with path:line cites

local_verify

Bash lint/typecheck

PASS, or a triaged failure list

local_status

—

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 (qwen2.5-coder:7b)

deep (qwen3-coder:30b)

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 (local_explain)

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:

  1. Every path is resolved and confined to workspace_root; traversal is rejected.

  2. [sandbox] deny blocks .git, .env, keys, node_modules, and anything else you list. One rule set governs every route to a file's contents — read_file, grep and list_files alike — so search cannot return what read_file refuses to open.

  3. Original file contents are snapshotted in memory before the first write and restored automatically if the gate fails.

  4. local_explain and local_verify run with no write tools at all.

  5. 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.

  6. 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 tools
local_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

    A4.6/5.0

    Scored across 4 tools

    Disambiguation5/5

    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.

    Naming Consistency5/5

    All four tools follow a strict local_<verb> pattern (local_edit, local_explain, local_verify, local_status). The convention is predictable and unambiguous throughout.

    Tool Count5/5

    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.

    Completeness4/5

    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

    Related MCP Servers

    • A
      license
      Not graded
      quality
      D
      maintenance
      Enables 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.
      27
      AGPL 3.0
    • A
      license
      A
      quality
      D
      maintenance
      Enables 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.
      11
      372 npm
      3
      Apache 2.0
    • A
      license
      Not graded
      quality
      B
      maintenance
      Enables 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 PyPI
      11
      MIT