codex-local-ollama-mcp

中文说明

codex-local-ollama-mcp adds one deliberately narrow MCP tool, local_text, to Codex. It asks a local Ollama instance to draft a transformation of text that you supplied. Codex remains the planner and must review the resulting draft before replying.

This is a GitHub-only project release. The package is private and is not published to npm.

Capability boundary

The server exposes exactly one stdio MCP tool and accepts exactly one local model: qwen3.5:9b at http://127.0.0.1:11434. It only supports self-contained, read-only transformations of user-provided text:

• translate

• summarize

• rewrite

• extract

• classify

It does not execute commands, access files, write files, make Git changes, browse the web, use non-loopback network endpoints, receive tool definitions, or make decisions. Do not use it for current facts, code or operational work, or financial, medical, legal, security-sensitive, or other high-stakes work. Use Codex's normal tools for exact calculations and deterministic work.

The output is labeled Local draft with its model and mode. Treat it as a draft, not verified information.

For these simple draft transformations, the server deliberately sends the fixed Ollama request option think: false to disable qwen3.5 thinking and reduce latency. This is server-side only: callers cannot configure it, and it does not broaden the capability or safety boundaries. It is not a latency guarantee.

Related MCP server: mcp-ollama

Requirements

• Node.js 22 or newer

• Ollama available on PATH

• The exact local model qwen3.5:9b

• The Codex CLI on PATH; it registers the server used by Codex desktop or the CLI

• Codex desktop if you want to use the desktop interface

Keep Ollama bound to its local loopback default. Do not expose Ollama on your LAN or the public internet for this integration.

Install

Clone this repository, then fetch the required model:

git clone https://github.com/kisara174/codex-local-ollama-mcp.git
cd codex-local-ollama-mcp
ollama pull qwen3.5:9b
ollama list
node --version
codex --version
./install.sh

install.sh checks Node, Ollama, the exact model, and the local codex command. It then runs npm ci, builds the server, and registers it as local-ollama with the local Codex CLI. It refuses to overwrite an existing registration of that name.

For desktop use, fully restart the Codex desktop app after installation. Then verify that local-ollama is connected in Settings → MCP Servers or type /mcp in Codex. CLI users can also inspect the registration with:

codex mcp get local-ollama

Using local_text

Ask Codex for a bounded transformation of text you include in your request. It may call the tool with this schema:

mode: translate | summarize | rewrite | extract | classify
input: required text, up to 12,000 characters
instruction: optional short formatting preference, up to 500 characters

The instruction is intentionally restrictive: use a simple output or formatting preference. These examples are accepted by the current validator:

mode: translate
input: Good morning.
instruction: Translate to Chinese and preserve formatting.

mode: summarize
input: <text you provide>
instruction: Use two bullet points.

mode: rewrite
input: <text you provide>
instruction: Use a professional tone.

mode: extract
input: <text you provide>
instruction: Return a JSON list.

mode: classify
input: Category choices: billing, technical, account. Text: I cannot sign in.
instruction: Return one line only.

Put category choices and extraction criteria in the supplied input when the instruction cannot express them as a formatting preference. The service rejects blank or oversized input, unsupported modes, oversized instructions, and instructions that are not accepted as short formatting/output preferences.

Errors and troubleshooting

Tool errors start with one of these codes:

• INVALID_REQUEST: Use a supported mode, non-blank input within the limit, and a short formatting preference.

• OLLAMA_UNAVAILABLE: Start Ollama locally and confirm it remains reachable at its loopback default (127.0.0.1:11434). Do not solve this by exposing it to a LAN.

• MODEL_UNAVAILABLE: Run ollama pull qwen3.5:9b, then confirm the exact name appears in ollama list.

• OLLAMA_TIMEOUT: The local request has a 60-second bounded timeout. Retry a smaller transformation after checking that the local machine is not overloaded; the bound does not promise that every request will finish within 60 seconds.

• OLLAMA_BAD_RESPONSE: Restart the local Ollama service and retry. If it persists, inspect the local service logs without sharing sensitive data.

If installation reports an existing local-ollama registration, remove it only if it is the registration you intend to replace:

./uninstall.sh
./install.sh

Privacy and limits

The server sends only the text passed to local_text to the local Ollama HTTP endpoint on loopback. It does not send that request to a remote endpoint. The cloud Codex agent still sees the request and local draft in order to route, inspect, and answer, so this tool is not an end-to-end privacy boundary.

Using a local drafting step does not guarantee a reduction in cloud Codex or ChatGPT quota usage. The cloud agent still decides whether to call the tool and reviews the result.

Uninstall

From this checkout, run:

./uninstall.sh

It first checks that the local-ollama MCP registration runs exactly node <this-checkout>/dist/index.js, then removes that registration and this checkout's generated dist and node_modules directories. A missing, mismatched, or unreadable registration leaves the registration and generated files untouched. It does not remove Ollama, the model, or unrelated Codex settings.

Roadmap

After the v0.1.0 release has been observed in real use, the planned next phase is a separate evaluation corpus and runner for fixed local-text tasks. Its results will be reviewed before considering any broader local-model authority.