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

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

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:

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