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:
lmsonPATH, orLMSTUDIO_LMS_PATHset 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.txtis the concise routing and safety index.docs/LLM_USAGE.mdis the canonical agent operating manual.docs/mcp-tools.jsonis 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=truein 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: passmodelor configureLMSTUDIO_DEFAULT_MODEL.AUTH_REQUIRED: pass the local token throughLMSTUDIO_API_TOKEN; do not put it in source or URLs.CANCELLED: the MCP caller cancelled a long operation; the underlying request was aborted.lmsunavailable: setLMSTUDIO_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.
