English | Français

local-llm-mcp

An MCP server connecting Claude Code to LM Studio, to offload token-expensive work to a local model — without giving up the cloud model's agentic capabilities.

The idea

Claude keeps the driving seat; only the bulk work goes local.

The saving doesn't come from "use a cheaper model." It comes from keeping raw content out of the cloud context: the tools read the files themselves, on the server side, and only return the processed result.

Claude Code  ──(MCP call: "summarize src/**/*.cs")──►  local-llm-mcp
                                                              │
                                                              ├─ reads the files from disk
                                                              ├─ chunks if beyond local context
                                                              └─ queries LM Studio :1234
                                                                       │
Claude Code  ◄────────(≈700 tokens of summary)────────────────────────┘

Without this intermediary, reading a source tree burns tens of thousands of context tokens. With it, the cost shrinks to the size of the response.

Related MCP server: Claude Sidekick

Measurements

Recorded on a real Godot/C# project, with qwen3-coder-30b:

The ratio depends entirely on the task: a summary compresses a lot, an exhaustive extraction much less.

Requirements

• LM Studio with its local server running (port 1234 by default)

• Node.js 18 or later

• Claude Code

• A loaded model — see Model choice below

Tested on Windows 11. server.js has no Windows-specific dependency (the LM Studio CLI path is resolved per platform), but the helper script start-local.ps1 is PowerShell-specific.

Installation

git clone https://github.com/drangoht/local-llm-mcp.git
cd local-llm-mcp
npm ci

Then register the server with Claude Code, giving the absolute path to server.js:

claude mcp add local-llm --scope user -- node /absolute/path/to/local-llm-mcp/server.js

--scope user makes it available across all your projects. Use --scope project to limit it to the current repo.

Verification: claude mcp list should show local-llm: ✔ Connected.

Exposed tools

Model choice

Two aliases are exposed:

The chosen default is the larger model, which deserves an explanation since it's counter-intuitive. On the same short task, measured:

The smaller model is five times faster per token, but produces eighteen times more of them for an equivalent result. In useful output, the larger model wins. Also, the enable_thinking: false parameter has no effect on this model, and a max_tokens set too low makes it return an empty content — the server detects this case and reports it explicitly instead of silently returning an empty string.

Adjust to your hardware via LOCAL_MODEL_CODE / LOCAL_MODEL_LIGHT.

Automatic model loading

On startup, the server checks via lms ps --json that the model is loaded with sufficient context, and reloads it if not.

This check exists for a specific reason: LM Studio's defaultContextLength setting is 4096 tokens. Its just-in-time loading (justInTimeModelLoading) therefore brings the model back down to 4096 as soon as the TTL expires or the application restarts — and local_digest then breaks silently: truncated responses, no error raised. It's the most painful failure mode because it's invisible.

The check is non-blocking (the MCP handshake stays around 0.4 s) and costs nothing when the configuration is already correct. Disable it with LOCAL_AUTOLOAD=0.

start-local.ps1 (Windows) does the same thing from a terminal, useful for preloading the model before opening Claude Code to avoid waiting on the first call.

Configuration

All environment variables are optional.

Restricting reads

By default the server can read any file accessible to the user. To confine it to your code folders:

claude mcp add local-llm --scope user \
  --env LOCAL_ALLOWED_ROOTS="/path/to/projects" \
  -- node /absolute/path/to/local-llm-mcp/server.js

Timeouts on the Claude Code side

In ~/.claude/settings.json:

"env": {
  "MCP_TIMEOUT": "60000",
  "MCP_TOOL_TIMEOUT": "900000"
}

A generous MCP_TOOL_TIMEOUT is necessary: a local_map over several dozen files takes several minutes.

When to delegate locally, when to stay in the cloud

Short rule: local is for reducing volume, not for settling a question.

Limitations

• The local model makes mistakes. It misses edge cases and sometimes invents method names. Its output is a starting point to verify, never a conclusion on anything critical.

• Modest throughput on a GPU that doesn't fully fit the model in VRAM. On the reference setup (Radeon RX 9070, 16 GB), a 30B model in Q4 overflows by about 3.5 GB and runs at ~13.5 tok/s. A local_map over 40 files takes several minutes.

• No streaming: results arrive as a single block.

• A single resident model if VRAM is limited; switching between aliases forces a reload (~16 s for an 18 GB model).

Troubleshooting

License

MIT — see LICENSE.