# lmstudio-mcp

A production-oriented, local-only Model Context Protocol (MCP) stdio server for diagnosing, testing, benchmarking, and deliberately controlling LM Studio.

It talks only to a loopback LM Studio server, has no cloud fallback or telemetry, never downloads a model, and disables all mutations by default.

## Why this exists

LM Studio exposes several API families and model metadata does not prove runtime behavior. This server gives MCP clients one consistent interface and keeps three kinds of evidence separate:

- **DECLARED** — model metadata claims.
- **DETECTED** — passive endpoint or runtime observations.
- **VERIFIED** — a completed live test, such as a real tool-call round trip.

## Architecture

```mermaid
flowchart LR
  Client["MCP client<br/>Codex or another SDK client"] -->|"stdio"| Server["lmstudio-mcp"]
  Server -->|"HTTP on loopback only"| Native["LM Studio native API"]
  Server -->|"HTTP on loopback only"| OpenAI["OpenAI-compatible APIs"]
  Server -->|"spawn with argument arrays"| CLI["lms CLI"]
  Server --> Evidence["In-process capability evidence"]
  Evidence --> Snapshot["Canonical JSON + SHA-256 snapshot"]
```

## Requirements

- Node.js 20, 22, or 24
- LM Studio with its local server enabled
- Optional: `lms` on `PATH`, or `LMSTUDIO_LMS_PATH` set to the executable

The implementation is cross-platform TypeScript. macOS is live-verified; Linux and Windows are exercised by the CI matrix for build, unit, and MCP protocol behavior. Live LM Studio integration on those platforms remains environment-dependent and is not claimed by CI.

## Install and build

```sh
git clone https://github.com/Ka1y0/Tool_MCP_LMStudio.git
cd Tool_MCP_LMStudio
corepack enable
pnpm install --frozen-lockfile
pnpm build
pnpm test
```

`npm install`, `npm run build`, and `npm test` are also supported. Live integration tests skip when LM Studio is unavailable and never load, unload, or download models.

## Configuration

| Variable | Default | Meaning |
|---|---|---|
| `LMSTUDIO_BASE_URL` | `http://127.0.0.1:1234` | Must use `http://` and a loopback hostname. |
| `LMSTUDIO_API_TOKEN` | empty | Optional local bearer token; never persisted by this project. |
| `LMSTUDIO_MCP_ALLOW_MUTATIONS` | `false` | Enables the two explicit load/unload tools. |
| `LMSTUDIO_DEFAULT_MODEL` | empty | Default model identifier for tests. |
| `LMSTUDIO_REQUEST_TIMEOUT_MS` | `120000` | HTTP/CLI timeout, bounded to 250–300000 ms. |
| `LMSTUDIO_LOG_CAPTURE_MAX_SECONDS` | `30` | Log stream duration, bounded to 1–120 seconds. |
| `LMSTUDIO_LMS_PATH` | `lms` | `lms` executable name or absolute path. |

The server intentionally has no dotenv dependency. Pass variables from the MCP launcher; `.env.example` is only a reference.

## Register with Codex

Build first, then use absolute paths appropriate to your machine:

```sh
codex mcp add lmstudio-mcp \
  --env LMSTUDIO_BASE_URL=http://127.0.0.1:1234 \
  --env LMSTUDIO_MCP_ALLOW_MUTATIONS=false \
  --env LMSTUDIO_LMS_PATH=/absolute/path/to/lms \
  -- node /absolute/path/to/lmstudio-mcp/dist/index.js
```

Check registration with `codex mcp get lmstudio-mcp` and `codex mcp list`. A client session opened before registration may need to be restarted.

## Tools

The server exposes 18 tools:

| Tool | Class | Purpose |
|---|---|---|
| `lmstudio_status` | read-only | Health, versions, reachability, and model counts. |
| `lmstudio_list_models` | read-only | Downloaded model metadata. |
| `lmstudio_list_loaded_models` | read-only | Loaded runtime instances. |
| `lmstudio_inspect_model` | read-only | Static and runtime model information. |
| `lmstudio_test_inference` | inference | One bounded native, Chat Completions, or Responses request. |
| `lmstudio_test_endpoints` | inference | Classify the three API families. |
| `lmstudio_test_tool_calling` | inference | Deterministic non-streaming tool-call round trip. |
| `lmstudio_test_streaming_tool_calling` | inference | Streamed call reassembly, execution, continuation, progress, and cancellation. |
| `lmstudio_test_structured_output` | inference | Schema enforcement versus JSON/prompt-only output. |
| `lmstudio_capabilities` | read-only | DECLARED/DETECTED/VERIFIED summary. |
| `lmstudio_export_capability_snapshot` | read-only | Secret-free canonical snapshot and SHA-256. |
| `lmstudio_security_audit` | read-only | Bind, CORS, auth, logging, and destination checks. |
| `lmstudio_benchmark` | inference | Small bounded streaming benchmark. |
| `lmstudio_capture_logs` | read-only | Bounded, redacted log capture with child cleanup. |
| `lmstudio_diagnose` | read-only | Findings, probable causes, and actions. |
| `lmstudio_validate_mcp` | read-only | Read-only validation of LM Studio's MCP config. |
| `lmstudio_load_model` | mutating | Load an already-downloaded model; disabled by default. |
| `lmstudio_unload_model` | mutating | Unload one explicit identifier; disabled by default. |

## For LLMs and Agents

Machine-oriented documentation is intentionally separate from this human overview:

- [`llms.txt`](llms.txt) is the concise routing and safety index.
- [`docs/LLM_USAGE.md`](docs/LLM_USAGE.md) is the canonical agent operating manual.
- [`docs/mcp-tools.json`](docs/mcp-tools.json) is generated from the actual MCP registry and contains every current tool schema plus operational metadata.

Run `pnpm docs:tools` after tool changes and `pnpm docs:check` to detect drift.

All tools with output schemas return both human-readable `content` and machine-readable `structuredContent`.

## Streaming verification

`lmstudio_test_streaming_tool_calling` uses one inert fixture, `lookup_test_record(742)`. It reconstructs fragmented call IDs, function names, and JSON arguments; rejects missing, malformed, duplicate, multiple, or schema-invalid calls; executes no shell/filesystem/network action; returns `{project, status, value}` to the model; and validates labeled fixture values in the streamed continuation. Final-answer comparison ignores punctuation delimiters but never missing labels, altered letters, or altered digits.

The tool emits MCP progress notifications only when the caller supplies a progress token. MCP cancellation aborts the underlying LM Studio fetch and is classified as `CANCELLED`. Only Chat Completions streaming is currently claimed as verified; other streaming API families remain unverified.

## Capability snapshots

`lmstudio_export_capability_snapshot` returns a versioned snapshot, its recursively key-sorted canonical JSON, and a lowercase SHA-256 digest. The hash covers the UTF-8 canonical snapshot only. Tokens, environment contents, home paths, model filesystem paths, and arbitrary raw API payloads are excluded. See [the schema contract](docs/CAPABILITY_SNAPSHOT.md).

## Mutation and privacy guarantees

- Non-loopback URLs and credential-bearing URLs are rejected at startup.
- Mutations require `LMSTUDIO_MCP_ALLOW_MUTATIONS=true` in the server process.
- Loading never downloads; unloading requires one identifier and never uses `--all`.
- CLI calls use `spawn(executable, args)` without a shell.
- Errors and logs redact tokens, authorization values, API keys, passwords, and secrets.
- No analytics, telemetry SDK, cloud inference, or remote destination is present.

## Development

```sh
pnpm build
pnpm test:unit
pnpm test:mcp
pnpm test:integration   # live tests skip if LM Studio is unavailable
pnpm check
```

Tests cover configuration boundaries, redaction, mutation guards, protocol structured content, tool-call adversaries, streamed delta reconstruction, cancellation, snapshot canonicalization, and live endpoints. CI deliberately excludes environment-dependent live LM Studio assertions.

## Troubleshooting

- `serverRunning: false`: start LM Studio's local server and retain its loopback bind.
- `MODEL_REQUIRED`: pass `model` or configure `LMSTUDIO_DEFAULT_MODEL`.
- `AUTH_REQUIRED`: pass the local token through `LMSTUDIO_API_TOKEN`; do not put it in source or URLs.
- `CANCELLED`: the MCP caller cancelled a long operation; the underlying request was aborted.
- `lms` unavailable: set `LMSTUDIO_LMS_PATH`; API-only functions can still work.
- A reasoning model may consume a small output budget before producing visible content; bounded tools report reasoning-only output separately.

Historical local verification reports are in [docs/DIAGNOSTIC_REPORT.md](docs/DIAGNOSTIC_REPORT.md) and [docs/V0.2_CAPABILITY_REPORT.md](docs/V0.2_CAPABILITY_REPORT.md). They are evidence from one environment, not universal compatibility claims.

## Contributing and security

See [CONTRIBUTING.md](CONTRIBUTING.md), [SECURITY.md](SECURITY.md), and [CODE_OF_CONDUCT.md](CODE_OF_CONDUCT.md). The project is licensed under the [MIT License](LICENSE).