mcp-ollama

MCP server wrapping local Ollama models for offload from API-priced orchestrators.

Exposes nine tools that pass work to a local model (text generation, summarisation, code tasks, mechanical transforms, commit/PR/changelog drafting). The orchestrator decides what to route locally; this server does the routing.

• Transport: stdio

• Runtime: Node 18+

• Default model: hermes3:8b (override via OLLAMA_MODEL)

• Ollama host: http://localhost:11434 (override via OLLAMA_HOST)

• Ships no model weights, no cloud call-outs, no telemetry. Every request stays on the host where Ollama is running.

• License: Apache-2.0

Why

Orchestrators priced by the token (Claude Code, Cursor, the Anthropic API, Cline, Aider) pay for every classification, every docstring, every commit message. Most of that work doesn't need a frontier model. Routed to Ollama on the same machine, the same work is free and faster. mcp-ollama is the routing surface.

The orchestrating model decides what to route where. This server is plumbing - it does not try to be clever about task classification. Pick the right tool, pass the text, get a result back.

Install

Install (from source)

git clone https://github.com/true-alter/mcp-ollama.git
cd mcp-ollama
npm install
npm run build

That builds dist/index.js, which is the path the client configuration below points at. There is no registry install. This package is not published to npm, so npm install @truealter/mcp-ollama will not resolve.

You also need a running Ollama instance with at least one model pulled:

# Default - 8B, fast, good for classifications and short generations
ollama pull hermes3:8b

# Optional - code-specialised, heavier, better for local_code tasks
ollama pull qwen2.5-coder:32b

Docker

docker build -t mcp-ollama .
docker run -i --rm \
  -e OLLAMA_HOST=http://host.docker.internal:11434 \
  -e OLLAMA_MODEL=hermes3:8b \
  mcp-ollama

The supplied Dockerfile points at host.docker.internal:11434 so the container reaches Ollama on the host.

Run (stdio)

node dist/index.js

Stdio servers are launched by the MCP client (Claude Code, Cursor, etc.) - running it directly is only useful for debugging.

Configure Claude Code

claude mcp add --transport stdio ollama -- node /absolute/path/to/mcp-ollama/dist/index.js

Or in ~/.claude/settings.json:

{
  "mcpServers": {
    "ollama": {
      "transport": "stdio",
      "command": "node",
      "args": ["/absolute/path/to/mcp-ollama/dist/index.js"],
      "env": {
        "OLLAMA_HOST": "http://localhost:11434",
        "OLLAMA_MODEL": "hermes3:8b"
      }
    }
  }
}

Tools

Full tool schemas are exposed over MCP introspection - any MCP-aware client will enumerate them automatically.

Environment variables

Any tool call may override model explicitly - the env default only applies when unset. local_code tends to work better with a code-specialised model passed per-call, while local_summarize and local_draft are fine on the default.

Model selection guidance

Use local_models at session start if you're unsure what's available on a host.

Troubleshooting

Ollama error 404 when calling a tool. The model isn't pulled. Run ollama pull <name> or call local_pull from the client.

fetch failed / connection refused. Ollama isn't running, or OLLAMA_HOST points somewhere wrong. Verify with curl $OLLAMA_HOST/api/tags. Inside a container, localhost is the container itself - use host.docker.internal on macOS/Windows or a bridge IP on Linux.

Tool calls feel slow. First call to a cold model incurs a load. Subsequent calls within the same Ollama process are much faster. If the model is larger than available VRAM, Ollama falls back to CPU - watch ollama ps to confirm.

Empty or truncated output. max_tokens defaults to 2048 per tool. For long generations, pass max_tokens explicitly in the tool call.

Security posture

mcp-ollama makes no network call of its own beyond the configured OLLAMA_HOST. It ships no telemetry, no analytics, no auto-update pinger. Tool inputs are forwarded to Ollama's HTTP API verbatim and the response is relayed back; the server itself is stateless between calls.

If you run Ollama on localhost (the default) the entire loop stays on the host. If you point OLLAMA_HOST at a remote endpoint, treat that endpoint's security posture as authoritative - a typo sending prompts to a third-party host is trivially possible.

To report a security issue, see SECURITY.md.

Contributing

Bug reports and small patches welcome - see CONTRIBUTING.md. Larger design changes: please open an issue first so we can talk about scope before you invest time.

Part of ALTER

mcp-ollama is maintained by ALTER as part of the identity infrastructure for the AI economy. The ALTER identity MCP server is hosted at mcp.truealter.com - see @truealter/sdk for the TypeScript client.

License

Apache License 2.0. See LICENSE for the full text. Copyright 2026 Alter Meridian Pty Ltd (ABN 54 696 662 049).