ollama-mcp

An MCP server that lets an agent — Claude Code, or anything else speaking MCP — hand work to your local Ollama models.

The point is not to wrap the Ollama API. It is to give a frontier-model agent a cheap local tier it can delegate to: summarizing a 40KB log, extracting fields from twenty dumped files, reformatting JSON — mechanical, high-token, low-judgment work that burns expensive context for no benefit.

No model name appears anywhere in src/. Models are discovered live from the daemon and addressed by capability or by role. Pull a new model and it becomes usable within a minute, with no code change, no config edit, and no restart. That property is enforced in CI, not by convention.

Install

git clone https://github.com/Clickt-Digital-Marketing-Inc/ollama-mcp.git
cd ollama-mcp
npm install
npm run build

Register with Claude Code (user scope — available in every project):

claude mcp add --scope user ollama -- node /absolute/path/to/ollama-mcp/dist/src/index.js

Or add it to any MCP client's config:

{
  "mcpServers": {
    "ollama": {
      "command": "node",
      "args": ["/absolute/path/to/ollama-mcp/dist/src/index.js"]
    }
  }
}

Requires Node ≥ 20 and a running Ollama daemon. No configuration is needed to start — roles resolve by capability against whatever you already have installed.

Related MCP server: Ollama MCP Server

Tools

ollama_dispatch

One local generation. The main tool.

{ "prompt": "Summarize this changelog in 3 bullets.", "model": "role:summarize" }

Supports system, multi-turn messages, structured output via format (either "json" or a full JSON Schema), tool-calling passthrough, the usual sampling controls, and files/file_globs (below).

Every response ends with a metrics line:

[ollama model=<name> via=role:summarize→role:fast→caps:completion
 tok=3120→412 dur=6.4s load=0.0s rate=64tok/s ctx=131072 done=stop think=off]

model and via are always present. A dispatcher that silently routes to the wrong model is the most expensive failure mode there is, so the resolution trail is never hidden.

ollama_dispatch_batch

Fan-out over many prompts. Items are grouped by resolved model and groups run sequentially, so a cold load is paid at most once per model instead of thrashing VRAM. Results come back in input order regardless of execution order, and one failing item never voids the run.

ollama_models

Discovery: capabilities, context window, size, residency. Two things worth knowing:

• refresh: true re-reads the daemon after you pull something.

• explain_selector: "role:coder" dry-runs the resolver and prints the whole fallback chain without spending a generation. When routing surprises you, start here.

ollama_lifecycle

status / warm / unload. A large model can take ~12s to load and occupy tens of GB of VRAM, so warming before a batch and unloading afterwards are both real operations you'll want.

Choosing a model

Three grammars for the model field:

Ambiguity is refused rather than guessed: if foo matches three installed tags, you get an error listing them. A wrong-model run is invisible in the output, so it is not something to coin-flip.

Roles

A role is an ordered chain. Each link is a literal name, another role, or a capability predicate — and the first link that resolves wins:

{
  "roles": {
    "coder": { "chain": ["some-coding-model", "some-fallback-model", "caps:completion"] }
  }
}

If the preferred model isn't installed, the chain falls through. This is the future-proofing story: the chain documents your intent even when the model isn't there yet, and starts routing to it the moment you pull it.

Built-in roles — all defined purely as capability predicates, so they work against any install: general, fast, big, reasoner, coder, vision, tools, embed, summarize, extract.

Adding a model

Three ways, in increasing order of commitment:

1. Just pull it. ollama pull <model>. Within ~60s it joins the candidate pool for every role and capability it qualifies for, and is addressable by name. Nothing else to do.

2. Pin a preference. Add it to the front of a role's chain in ollama-mcp.config.json.

3. Use an env var, no file at all. OLLAMA_MCP_ROLE_CODER="model-a,model-b,caps:completion". OLLAMA_MCP_ROLE_<NAME> is parsed generically, so this also creates roles — OLLAMA_MCP_ROLE_TRANSLATOR=... gives you role:translator with no code change.

Config is discovered at $OLLAMA_MCP_CONFIG, then ./ollama-mcp.config.json, then ~/.config/ollama-mcp/config.json; first hit wins. A malformed config is non-fatal — the server logs, falls back to defaults, and warns on the first response, because a typo should never take the server down.

File-aware inputs

files and file_globs make the server read files and feed them to the local model:

{ "prompt": "Extract every TODO with its file and line.",
  "file_globs": ["src/**/*.ts"],
  "model": "role:extract" }

File contents never enter the calling agent's context — only the local model's distilled answer comes back. For large inputs this is the whole reason the server is worth having.

Safety boundary

This is an LLM directing a server to read a disk, so the boundary is explicit:

• Root allowlist. Only paths under OLLAMA_MCP_FILE_ROOTS (colon-separated; defaults to the working directory) are readable. Paths are realpath-resolved before the check, so ../ traversal and symlink escapes both fail closed.

• Sensitive-file deny-list, on by default: .env*, *.pem, *.key, id_rsa*, .ssh/**, .aws/**, .git/config, and anything named like a credential or secret. These can only be read by naming the file explicitly and passing allow_sensitive: true. A glob can never pull one in, whatever the flag says.

• Caps: 1MB per file, 4MB total, 50 files. Exceeding a cap is a hard error naming the file — never a silent drop.

• Every file actually read is listed in the response, so an unexpected read is visible rather than silent.

Provenance, not immunity. File contents are untrusted input flowing into a model whose output comes back to your agent. The server wraps each file in explicit delimiters marking it as data rather than instructions. That makes the provenance legible; it does not make the output safe to act on blindly. Treat a dispatch result as untrusted text.

The thinking-token trap

Worth understanding, because it will bite you with any reasoning-capable model.

Reasoning tokens and answer tokens are drawn from the same num_predict budget. Set the cap too low with thinking enabled and the model spends the entire budget reasoning, then returns content: "" with done_reason: "length" — an HTTP 200, success-shaped, completely empty result. An agent will happily treat that as "the summary is empty" and carry on.

Three defences:

1. think defaults to off. This server is for mechanical work where reasoning is cost without benefit. It's also capability-gated, so models that don't support thinking never receive the field.

2. An unsafely low num_predict is raised to a workable floor (with a visible warning) when thinking is on. num_predict is a cap, not a target — raising it can't make a good run worse, but leaving it converts a guaranteed-empty result into a wasted model load.

3. The exhausted case is detected and returned as an error, quantified, with ranked fixes — never as an empty success.

Configuration

Precedence everywhere: per-call argument > env var > config file > built-in default.

Ranking defaults to residency-first because an already-loaded model answers in seconds while a cold one can take ~12s to load — for high-volume mechanical work, "already in VRAM" beats every other signal.

Development

npm run build
npm run test:unit               # no daemon required
npm run check:no-model-literals # CI gate: no model names in src/
npm run smoke                   # end-to-end, needs a live daemon

The codebase is deliberately split: src/ is pure except for four files (index.ts, ollama/client.ts, registry/fetch.ts, config/load.ts). Model resolution, request shaping, response classification, batching and path validation are all total functions over plain data, tested against response fixtures captured from a real daemon. That's why the test suite needs no Ollama and CI is green on a clean runner.

Credits

Design inspiration for the file-aware tooling — reading files server-side so their contents never traverse the agent's context — came from Jadael/OllamaClaude. No code was copied; that project is AGPL-3.0 and this one is independently implemented under MIT.

License

MIT © Clickt Digital Marketing Inc.