# lmstudio-mcp

An [MCP](https://modelcontextprotocol.io/) server that lets Claude Code delegate easy, mechanical tasks (summaries, boilerplate, reformatting, test data) to local models running in [LM Studio](https://lmstudio.ai/) — keeping Claude as the orchestrator while cheap work runs locally.

## Tools

| Tool | Purpose |
|------|---------|
| `ask_local_model` | Send a self-contained prompt to a local model. Optional `model`, `system`, `temperature`, `max_tokens`. |
| `list_local_models` | List models currently available in LM Studio. |

The `ask_local_model` tool description tells Claude *when* to delegate (mechanical, low-stakes tasks with small context) so delegation happens automatically once the server is installed.

## Requirements

- Node.js 18+
- LM Studio running with its local server enabled (default `http://localhost:1234`) and at least one chat model loaded

## Setup

```bash
git clone https://github.com/zmagyar/lmstudio-mcp.git
cd lmstudio-mcp
npm install

# register with Claude Code (user scope = available in all projects)
claude mcp add --scope user lmstudio -- node "$(pwd)/index.js"
```

Start a new Claude Code session and try: *"use the local model to summarize this file"*.

## Configuration

Set via environment variables (e.g. in the server's entry in `~/.claude.json`):

| Variable | Default | Purpose |
|----------|---------|---------|
| `LMSTUDIO_BASE_URL` | `http://localhost:1234/v1` | LM Studio API endpoint |
| `LMSTUDIO_DEFAULT_MODEL` | `openai/gpt-oss-120b` | Model used when Claude doesn't specify one |

Set `LMSTUDIO_DEFAULT_MODEL` to a model you actually have loaded — run `lms ls` or check the LM Studio UI.

## Making delegation automatic

Out of the box, Claude only uses the tools when you ask ("use the local model to…"). Two extra steps make it delegate small tasks on its own, without prompting you each time — sample files for both are in [`examples/`](examples/):

1. **Standing instructions** — append the contents of [`examples/CLAUDE.md.sample`](examples/CLAUDE.md.sample) to your `~/.claude/CLAUDE.md` (create it if missing). It's loaded into every session and tells Claude *when* to delegate: mechanical, low-stakes tasks like log summaries, boilerplate, and reformatting — and when not to.

2. **Pre-approved permissions** — merge the `permissions` block from [`examples/settings.json.sample`](examples/settings.json.sample) into your `~/.claude/settings.json`, so the tool calls don't stop at a permission prompt. If you already have a `permissions.allow` array, just add the two entries to it.

Both changes take effect in your next Claude Code session. Try *"summarize the last 200 lines of this build log"* — the `lmstudio` tool should fire without being asked for.

Note that delegation is judgement-based: Claude decides per-task using those instructions, so tune the wording in your `CLAUDE.md` if it delegates too eagerly or too rarely.

## License

MIT