ollama-code-mcp
This server lets Claude Code (or any MCP client) delegate coding tasks to a local or LAN Ollama instance running a Qwen3 model.
Generate new code from natural-language instructions, with optional language and context file.
Review code for bugs, security issues, and simplifications, inline or from a file.
Refactor code behavior-preservingly, returning the updated code (no disk writes).
Diagnose and fix bugs given code and an optional error message/symptom.
Write tests for code, with optional framework specification.
Explain what code does, controlling whether the model reasons deeply.
Review git diffs (inline or from a file) PR-review style with optional context.
Batch-refactor multiple files matching a glob pattern, sequentially; can dry-run to preview diffs or write changes to disk.
Check connectivity to the Ollama host and list available models via a health-check tool.
Toggle Qwen3 extended reasoning (/think or /no_think) per call via a
thinkparameter.
Allows delegation of coding tasks such as code generation, review, refactoring, test writing, explanation, and batch processing to a local or LAN Ollama instance running a Qwen3 model.
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-code-mcp generate a Python function to download a file from a URL"
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-code-mcp
An MCP server that lets Claude Code delegate
coding tasks to a local (or LAN) Ollama instance running
a Qwen3 model. Point it at a GPU box on your network -- a Tesla V100 running
qwen3.8:27b-mtp-q8-precise, for example -- and Claude Code can hand off boilerplate
generation, test writing, diff review, and batch refactors to it instead of
spending cloud tokens and context window on them.
See CLAUDE.md for the routing guidance Claude Code reads to
decide what to delegate versus what to keep in the cloud.
Why
Saves Claude's context window. The file-aware tool variants take a
file_path(ordiff_file, or aglob_patternfor batches) and read the content server-side, so Claude never has to paste large files into a tool call just to hand them off.Uses idle GPU capacity. If you already run Ollama on a home GPU box or in a k3s cluster, this turns that capacity into a first-class Claude Code tool instead of a chat window you have to copy-paste into.
Fails safe. If Ollama is unreachable, times out, or the model isn't pulled, tools return a clear, non-fatal message telling Claude to just handle the task itself rather than getting stuck retrying.
Related MCP server: mcp-local-llm
Tools
Tool | Purpose | Inputs |
| Generate new code from an instruction |
|
| Review code for bugs, security issues, simplifications |
|
| Refactor code per an instruction, behavior-preserving |
|
| Diagnose and fix a bug |
|
| Write tests for given code |
|
| Explain what code does |
|
| Review a git diff, PR-review style |
|
| Apply an instruction across files matching a glob, sequentially |
|
| Health check: reachability, configured model, available models | -- |
Every tool (except ollama_status) accepts a think: bool parameter. This
toggles Qwen3's extended reasoning by appending /think or /no_think to
the prompt (see Think mode below). All coding tools default to
think=True; explain_code defaults to False since explanations are
usually fast enough without it.
code / file_path (and diff / diff_file) pairs are mutually exclusive
-- pass exactly one. File paths are resolved and confined to
OLLAMA_MCP_ALLOWED_DIR (see Configuration); attempts to
read or write outside it are rejected.
refactor_code returns the refactored code as text -- it does not touch
disk. batch_refactor is the one tool that can write files, and only when
called with dry_run=False; by default it returns a unified diff per file
so you can review before applying.
Installation
Requires Python 3.10+.
git clone git@github.com:darthzen/ollama-code-mcp.git
cd ollama-code-mcp
pip install -e .Or with uv:
uv pip install -e .Register with Claude Code
Add to your Claude Code MCP config (claude mcp add or the mcpServers
block in your settings), pointing OLLAMA_BASE_URL at wherever Ollama
actually listens -- commonly a LAN address, not localhost, since the model
runs on a dedicated GPU host:
{
"mcpServers": {
"ollama-code": {
"command": "ollama-code-mcp",
"env": {
"OLLAMA_BASE_URL": "http://ollama.ash4d.com:11434",
"OLLAMA_MODEL": "qwen3.8:27b-mtp-q8-precise",
"OLLAMA_MCP_ALLOWED_DIR": "/Users/you/code"
}
}
}
}Or run it straight from the repo without installing:
{
"mcpServers": {
"ollama-code": {
"command": "/path/to/ollama-code-mcp/.venv/bin/python",
"args": ["-m", "ollama_code_mcp.server"],
"env": { "OLLAMA_BASE_URL": "http://ollama.ash4d.com:11434" }
}
}
}OLLAMA_MCP_ALLOWED_DIR should be set to the project root (or a parent of
every project) you want file-aware tools to be able to read/write. It
defaults to the server's current working directory.
Configuration
All configuration is via environment variables:
Variable | Default | Description |
|
| Where Ollama listens. LAN addresses and bare |
|
| Model tag to use, as shown by |
|
| Request timeout in seconds. Defaults to 15 minutes to allow large generations/refactors on modest hardware. |
|
| TCP connect timeout in seconds. |
|
| Context window passed to Ollama's |
| server CWD | Base directory that file-aware tools are confined to. |
|
| Per-file size cap for server-side reads. |
|
| Max files processed per |
|
| Default value for each tool's |
|
| How the think toggle reaches the model. |
|
|
|
|
| Bind host for |
|
| Bind port for |
Think mode
Qwen3 exposes a soft toggle for its extended chain-of-thought reasoning:
appending /think or /no_think to the end of a prompt turns it on or off
for that turn. This server does that automatically based on each tool's
think parameter, and separates the model's <think>...</think> block from
its final answer in the response, so you get:
[review_code] via qwen3.8:27b-mtp-q8-precise (4213 ms, 812 tokens)
<the actual review>
--- model reasoning ---
<the model's chain of thought, if think=True>Use think=True (the default for most tools) for review, refactor, fix, and
test-writing tasks where reasoning quality matters. Use think=False for
quick, low-stakes generations or explanations where latency matters more.
Running standalone
OLLAMA_BASE_URL=http://ollama.ash4d.com:11434 ollama-code-mcpBy default this speaks MCP over stdio, which is what Claude Code expects
when it spawns the process itself. To run it as a long-lived network
service instead (for the Docker/k8s deployment below), set
MCP_TRANSPORT=streamable-http.
Docker
docker build -t ollama-code-mcp .
docker run --rm -p 8765:8765 \
-e OLLAMA_BASE_URL=http://ollama.ash4d.com:11434 \
-e MCP_TRANSPORT=streamable-http \
-v /path/to/your/code:/workspace \
-e OLLAMA_MCP_ALLOWED_DIR=/workspace \
ollama-code-mcpClaude Code would then connect to it as a remote MCP server at
http://<host>:8765/mcp.
Kubernetes / k3s
Manifests are in k8s/. They assume Ollama is already running in
the same cluster (e.g. via the ollama-helm chart with a LoadBalancer
service on port 11434, as in ollama-current-values.yaml), and reach it over
the cluster-internal service DNS name rather than a LAN IP:
kubectl apply -f k8s/configmap.yaml
kubectl apply -f k8s/deployment.yaml
kubectl apply -f k8s/service.yamlk8s/configmap.yaml ships pointing OLLAMA_BASE_URL at
http://ollama.ash4d.com:11434; edit it if your Ollama lives elsewhere
(e.g. the cluster-internal http://ollama.ollama.svc.cluster.local:11434
when both run in the same cluster). Adjust the
image reference in k8s/deployment.yaml to wherever you push the built
image. The manifests expose the server via streamable-http on a ClusterIP
service fronted by an Ingress at https://mcp-ollama.ash4d.com/mcp
(k8s/ingress.yaml). TLS is required because Claude's custom-connector UI
only accepts https URLs; the host resolves to a private IP, so provision the
cert via cert-manager DNS-01 or an existing wildcard secret (see the comments
in ingress.yaml). Register the connector in Claude (desktop or Claude Code)
as https://mcp-ollama.ash4d.com/mcp.
Security notes
File-aware tools are confined to
OLLAMA_MCP_ALLOWED_DIRvia path resolution + containment checks -- paths that resolve outside it (e.g.../../etc/passwd) are rejected.batch_refactorwrites are opt-in (dry_run=False) and capped in count (OLLAMA_MCP_MAX_BATCH_FILES) and per-file size (OLLAMA_MCP_MAX_FILE_BYTES).This server has no authentication of its own. If you deploy it with a network transport (
sse/streamable-http), keep it on a trusted LAN or put it behind a network policy / VPN -- do not expose it to the public internet.
Development
pip install -e ".[dev]"
pytestTests mock all Ollama HTTP calls (via respx) and use tmp_path for file
operations, so they run offline and don't need a real Ollama instance.
License
MIT -- see LICENSE.
Available Tools
9 toolsbatch_refactorA
Apply a refactor instruction to every file matching a glob pattern, sequentially.
glob_pattern matches relative paths under root_dir (default: the
server's allowed base directory), e.g. "src/**/*.py". Files are
processed one at a time against the local model. With dry_run=True
(the default) nothing is written -- you get a unified diff per file to
review first; set dry_run=False to write accepted changes to disk.
Large match sets are capped (see OLLAMA_MCP_MAX_BATCH_FILES) to avoid
runaway sequential runs.
Inputs: instruction (required), glob_pattern (required), think, dry_run, +1 more. Returns: result
code_review_diffA
Review a git diff (e.g. git diff main...HEAD) as if for a pull request.
Provide exactly one of diff (inline diff text) or diff_file (a
server-side path to a saved diff). context can carry the PR
description or any background the model should know.
Inputs: diff, think, context, diff_file. Returns: result
explain_codeA
Explain what code does, including control/data flow and non-obvious behavior.
Provide exactly one of code or file_path. Explanations are usually
fast enough that think=False (the default) is sufficient.
Inputs: code, think, file_path. Returns: result
fix_codeA
Diagnose and fix a bug in code, given an optional error message or symptom.
Provide exactly one of code or file_path. Include error_message
(a stack trace, test failure, or description of wrong behavior) whenever
you have one -- it substantially improves fix quality.
Inputs: code, think, file_path, error_message. Returns: result
generate_codeA
Generate new code from a natural-language instruction using the local Ollama model.
Pass context_file (a server-side path) instead of pasting an existing
file's contents to give the model style/API context without spending
your own context window on it. Set think=False for faster, simpler
generations; leave think=True for anything non-trivial.
Inputs: instruction (required), think, language, context_file. Returns: result
ollama_statusA
Check connectivity to the configured Ollama host and report available models.
Call this first if other tools are failing, or proactively before a batch of delegated work, to confirm the local model is reachable and pulled before relying on it.
Inputs: no named parameters. Returns: result
refactor_codeA
Refactor code according to an instruction, preserving external behavior.
Provide exactly one of code or file_path. Returns the full refactored
code plus a summary of changes; this tool does not write files itself --
use batch_refactor if you want changes applied to disk.
Inputs: instruction (required), code, think, file_path. Returns: result
review_codeA
Review code for correctness bugs, security issues, and simplification opportunities.
Provide exactly one of code (inline text) or file_path (a server-side
path read directly by this tool, saving your context window). focus
can narrow the review, e.g. "concurrency" or "input validation".
Inputs: code, focus, think, file_path. Returns: result
write_testsA
Write tests covering the golden path and realistic edge cases for given code.
Provide exactly one of code or file_path. Set framework (e.g.
"pytest", "jest") to match your project's conventions; otherwise the
model infers one from the code's language.
Inputs: code, think, file_path, framework. Returns: result
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 9 tools
Each tool has a clearly distinct purpose: code generation, explanation, review, debugging, refactoring (single and batch), test writing, diff review, and status check. No two tools overlap in functionality.
All tools follow a consistent verb_noun snake_case pattern (e.g., explain_code, fix_code, batch_refactor). No mixed conventions or vague names.
9 tools is a well-scoped set for a code assistance server. It covers the essential operations without being overwhelming or too sparse.
The set covers generation, explanation, review, debugging, refactoring, test writing, and status checking. Minor gaps like code documentation or execution are absent, but the core workflow is well-supported.
Maintenance
Related MCP Connectors
Shared memory MCP server for Claude Code, Codex, Gemini CLI and Cursor. Cited, editable.
An MCP server that gives your AI access to the source code and docs of all public github repos
Augments MCP Server - A comprehensive framework documentation provider for Claude Code
Related MCP Servers
- AlicenseNot gradedqualityDmaintenanceAn MCP server that provides agentic code review powered by OpenAI-compatible models, designed for use with Claude Code.1MIT
- AlicenseNot gradedqualityCmaintenanceMCP server that lets Claude Code delegate mechanical tasks to a local LLM for summarization, classification, extraction, and drafting.15MIT
- FlicenseNot gradedqualityDmaintenanceMCP server that lets Claude Code offload simple tasks like code explanation, writing tests, and adding comments to a local Ollama model, saving Claude API tokens.-
- FlicenseNot gradedqualityDmaintenanceMCP server that lets Claude Code dispatch tasks to the LiteLLM gateway, supporting both local Ollama models and Anthropic models via the gateway.-