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.

Related MCP server: Msty Local Ops

Architecture

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

git clone https://github.com/Ka1y0/lmstudio-mcp.git
cd lmstudio-mcp
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

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:

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:

For LLMs and Agents

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

• llms.txt is the concise routing and safety index.

• docs/LLM_USAGE.md is the canonical agent operating manual.

• 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.

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

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 and docs/V0.2_CAPABILITY_REPORT.md. They are evidence from one environment, not universal compatibility claims.

Contributing and security

See CONTRIBUTING.md, SECURITY.md, and CODE_OF_CONDUCT.md. The project is licensed under the MIT License.