Skip to main content
Glama
Philippe1964

LM Studio MCP Connector & Daemon

by Philippe1964

LM Studio MCP Connector & Daemon

Node.js Version TypeScript MCP Specification Platform License: MIT Version AI Generated

๐Ÿค– AI Transparency & Disclosure: This project, its source code, multi-OS installation scripts, and technical documentation were designed and authored with Artificial Intelligence assistance (Google Antigravity โ€” Models: Gemini 3.8 Flash for orchestration and local LM Studio models for cognitive reasoning). All code is systematically tested and validated by a strict Quality Gate.

A standalone, modern, ultra-resilient Model Context Protocol (MCP) server and daemon written in TypeScript to connect any agentic AI platform (Antigravity, Gemini, Claude Desktop, Cursor, VS Code) to one or multiple LM Studio instances via Stdio JSON-RPC or HTTP.


๐ŸŒŸ What's New in Version 2.0.0

  • ๐Ÿ”€ Multi-Instance Architecture & Load Balancing: Configure multiple LM Studio machines (local, LAN, dedicated GPU servers). Requests are automatically routed using the Least-Connections algorithm.

  • ๐Ÿ›ก๏ธ Automatic Failover & Circuit Breaker: If an instance times out, experiences connection errors, or shuts down, the connector seamlessly fails over to the next eligible instance.

  • โšก Antigravity Remote Fallback Directive: If all local instances become unavailable, the connector returns a structured diagnostic (REMOTE FALLBACK REQUIRED) instructing the calling agent to complete the task using its native remote LLMs without failing the execution.

  • ๐Ÿ–ฅ๏ธ HTTP Daemon & Embedded Real-Time Web GUI: Run with --daemon to host a web dashboard (http://127.0.0.1:9123/) for live monitoring (latency, in-flight requests, loaded models) and hot-reloading instance configurations without restarting.

  • ๐ŸŒ‰ Transparent Stdio Bridge: Standard Stdio clients automatically detect if the daemon is running and transparently forward requests to it, surfacing live metrics in the Web GUI without changing client configs.

  • ๐Ÿท๏ธ Role-Based Routing: Assign specialized roles (chat, embeddings, all) to instances (e.g. reserve fast embeddings to a specific machine without stalling heavy code completions).

  • โšก Zero Runtime Dependencies: Built 100% on native Node.js APIs (fetch, readline, node:http, node:events, AbortController).


Related MCP server: io.github.0xzr/freellmpool

๐Ÿ› ๏ธ Exposed MCP Tools

The connector exposes 5 standardized tools:

Tool

Description

Main Arguments

lmstudio_chat

Send a prompt/instruction to the local LM Studio model with auto-detection, load balancing, and remote fallback on complete outage.

prompt (required), system_prompt, model, temperature, max_tokens

lmstudio_list_models

List all AI models available across active instances in the pool.

None

lmstudio_embeddings

Compute vector embeddings for text using the configured local embedding model.

input (required), model

lmstudio_health

Probe latency, status, and active models across all configured instances.

None

lmstudio_pool_status

Retrieve a detailed JSON report of pool metrics, in-flight connections, and failover stats.

None


๐Ÿš€ Usage Modes

1. Standard Stdio Mode (Direct for Antigravity / Claude / Cursor)

In your MCP client configuration file (mcp_config.json, claude_desktop_config.json, etc.):

{
  "mcpServers": {
    "lmstudio": {
      "command": "node",
      "args": [
        "E:/SourceCode/LMStudio_MCP_Connector/dist/index.js",
        "--instances",
        "http://127.0.0.1:1234,http://192.168.1.50:1234"
      ]
    }
  }
}

2. Persistent HTTP Daemon & Web Dashboard

Run the connector as a background daemon:

node dist/index.js --daemon --port 9123 --instances "http://127.0.0.1:1234,http://192.168.1.50:1234"
  • Web Dashboard: Open http://127.0.0.1:9123/ in your browser.

  • MCP HTTP / RPC Endpoint: POST http://127.0.0.1:9123/mcp

  • Real-Time SSE Stream: GET http://127.0.0.1:9123/api/events


๐Ÿ’ป CLI Options

Options:
  --daemon, -d                   Run as persistent HTTP & SSE Daemon with embedded Web GUI
  --port, --daemon-port, -p <n>  Port for HTTP Daemon & Web GUI (default: 9123 or $LMSTUDIO_DAEMON_PORT)
  --daemon-url <url>             Explicit daemon URL for Stdio proxy (default: auto-detected 9123)
  --no-proxy, --standalone       Disable daemon proxy bridge and force local standalone execution
  --instances <urls/json>        Multi-instance list (comma-separated URLs or JSON array)
  --url, -u <url>                Primary LM Studio API URL (default: http://127.0.0.1:1234)
  --model, -m <name>             Model to use or fallback chat model (default: auto-detected)
  --fallback-chat-model <name>   Alias for --model
  --fallback-embed-model <name>  Fallback embedding model (default: text-embedding-nomic-embed-text-v1.5)
  --timeout, -t <ms>             HTTP Request timeout in ms (default: 60000)
  --check-health                 Perform a health check across all instances and exit
  --version, -v                  Display version number (v2.0.0)
  --help, -h                     Show help message

Advanced JSON Configuration for --instances or LMSTUDIO_INSTANCES

[
  { "id": "local-gpu", "name": "Desktop RTX 4090", "url": "http://127.0.0.1:1234", "roles": ["chat"], "priority": 2 },
  { "id": "lan-embed", "name": "Embedding Server", "url": "http://192.168.1.50:1234", "roles": ["embeddings"], "priority": 1 },
  { "id": "backup-cpu", "name": "Backup Node", "url": "http://192.168.1.60:1234", "roles": ["all"], "priority": 1 }
]

๐Ÿ›ก๏ธ Resilience & Antigravity Remote Fallback

When all local LM Studio instances are offline or unreachable:

  1. The connector does not hang or crash.

  2. The MCP tool returns isError: true with an explicit directive:

    โš ๏ธ [LM STUDIO OFFLINE - REMOTE FALLBACK REQUIRED]
    No local LM Studio instances are currently reachable.
    Antigravity is instructed to immediately fulfill this user request using its native remote LLM capabilities without failing the turn.
  3. The calling agent instantly recognizes the condition and fulfills the user request with its native cloud LLM (Gemini, Claude, GPT), ensuring zero workflow interruption.

  4. Once LM Studio is restarted, the background health probe automatically restores ONLINE status in real time.


๐Ÿงช Testing & Automated Quality Gate

The project is governed by an automated Quality Gate enforcing strict TypeScript typing and native tests:

# Run TypeScript strict checks and all 29 unit & integration tests:
node scripts/quality_gate_hook.js --cli

๐Ÿ“œ License

Distributed under the MIT License. See LICENSE for details.

Available Tools

5 tools
lmstudio_chatB

Send a prompt or instruction to the local LM Studio model and get the generated completion. If all local instances are offline, returns a directive instructing the agent to fallback to remote LLMs.

NameRequiredDescriptionDefault
modelNoOptional model identifier (defaults to currently loaded model in LM Studio)
promptYesThe prompt or instruction to send to the local model
max_tokensNoMaximum tokens to generate in response (default: 2048)
temperatureNoSampling temperature between 0.0 and 2.0 (default: 0.7)
system_promptNoOptional system instructions guiding the model behavior

TDQS

B3.3/5.0
Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations provided, the description carries the full burden. It usefully discloses that the tool returns a fallback directive when all local instances are offline, but it does not clarify permissions, whether prompts are stored, response streaming, or other operational behaviors.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is two focused sentences with the primary purpose front-loaded and a useful fallback condition second. There is no redundant or filler text.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

The description is adequate for a chat-completion tool with fully documented parameters, but with no output schema it does not fully describe the return shape beyond 'generated completion' and the offline fallback directive. Error handling and model-selection behavior are left implicit.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so the schema already documents prompt, model, max_tokens, temperature, and system_prompt. The description mentions sending a prompt and getting a completion but adds no parameter-level meaning beyond the schema.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description states a specific action and resource: send a prompt or instruction to the local LM Studio model and receive a generated completion. This clearly separates it from sibling tools like list_models, embeddings, health, and pool_status, though it does not explicitly name those alternatives.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description gives no explicit guidance on when to use this tool versus alternatives such as lmstudio_embeddings. It mentions fallback behavior when local instances are offline, but that is a behavioral note rather than usage guidance for choosing this tool.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

lmstudio_embeddingsB

Generate vector embeddings for input text using the local LM Studio embedding model.

NameRequiredDescriptionDefault
inputYesThe text to compute embeddings for
modelNoOptional embedding model identifier (defaults to loaded embedding model)

TDQS

B3.2/5.0
Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations, the description carries the full burden; it does disclose that inference is local and that the model defaults to the loaded embedding model, which is real context. It omits failure behavior when no model is loaded, whether inputs can be batched, and the output vector shape โ€” meaningful gaps for an unannotated tool.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

A single front-loaded sentence with no filler; verb and resource appear immediately.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness2/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

No output schema and no annotations, yet the description never states the return value (vector format/dimensions) or the model-must-be-loaded precondition. For a compute tool whose result shape is entirely undocumented, this leaves an agent under-informed.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, so both parameters are already documented, including the model default. The description adds nothing beyond 'input text' and the fact that the model is the local LM Studio one, so the baseline 3 applies.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

Specific verb (generate) plus resource (vector embeddings) over input text, naming the LM Studio embedding model. It is clearly distinct from the chat/completions siblings by operation type, though it never names them explicitly.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

No guidance on when to prefer embeddings over lmstudio_chat, no prerequisites (e.g., a model must be loaded), and no mention of alternatives such as lmstudio_list_models to verify availability. The use case is left entirely to inference.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

lmstudio_healthA

Check the health, status, latency, and loaded models of configured LM Studio instances.

NameRequiredDescriptionDefault

No parameters

TDQS

A3.5/5.0
Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations, the description carries the full burden. 'Check' implies a non-mutating probe and 'configured instances' implies multi-target scope, which is useful. However, it does not say whether the call fails when one instance is unreachable, whether it makes live network requests or reads cached state, or anything about timeouts โ€” important for a health probe.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

A single front-loaded sentence with no filler. The list of inspected attributes is packed efficiently and arrives before any agent could lose interest.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a zero-parameter tool with no output schema, the description adequately conveys what the agent will learn (health, latency, loaded models). It could go one step further and describe the per-instance result shape or degraded-instance behavior, but nothing essential to invoking it is missing.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The tool takes zero parameters, so there is nothing for the description to disambiguate; the baseline of 4 applies. The mention of 'configured' instances usefully signals that targeting comes from configuration rather than arguments.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description names a specific verb (Check) and resource (configured LM Studio instances) and enumerates what is inspected: health, status, latency, and loaded models. It is distinguishable from most siblings, though the overlap with lmstudio_pool_status and lmstudio_list_models is not explicitly addressed.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

There is no statement of when to call this versus lmstudio_pool_status (which likely reports similar instance-level information) or lmstudio_list_models. The usage is only implied by the word 'Check' โ€” no preconditions, no exclusions, no named alternatives.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

lmstudio_list_modelsA

List all AI models currently loaded and available across LM Studio instances.

NameRequiredDescriptionDefault

No parameters

TDQS

A3.5/5.0
Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided, so the description must carry the full behavioral burden. It communicates that the tool lists loaded/available models across instances, but does not clarify read-only behavior, permissions, pagination, or return behavior beyond the basic purpose.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single front-loaded sentence with no filler. It states the operation, resource, and scope efficiently.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a zero-parameter listing tool with no output schema, the description gives enough context to understand what will be listed. It could be slightly more complete by mentioning that it returns model identifiers/details or by distinguishing it from health/status tools.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

This tool has zero parameters, so there is no parameter semantics to explain. The schema is empty and the description appropriately does not invent parameter details.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description states a specific verb (List) and resource (AI models), and adds useful scope: currently loaded, available, and across LM Studio instances. It is clearly distinct from chat, embeddings, health, and pool-status siblings, though it does not explicitly contrast itself with them.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The intended use is implied by 'List all AI models,' but there is no explicit guidance on when to choose this over lmstudio_health or lmstudio_pool_status. No prerequisites or exclusions are stated.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

lmstudio_pool_statusB

Inspect multi-instance pool metrics, load balancing distribution, and failover status.

NameRequiredDescriptionDefault

No parameters

TDQS

B3.2/5.0
Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations exist, so the description must carry the full behavioral burden. 'Inspect' implies a read-only operation but this is never stated, and there's no mention of permissions, rate limits, what metrics are returned, or failure behavior.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

A single front-loaded sentence enumerating exactly what gets inspected, with no wasted words.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

No output schema exists, so the description could explain what the returned metrics look like (fields, format). It names the three categories inspected but leaves the return shape and read-only nature implicit, making it only minimally complete for a monitoring tool.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

With zero parameters and 100% schema coverage, there is nothing for the description to compensate for. Baseline 4 applies.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

Uses a specific verb 'inspect' paired with concrete resources (pool metrics, load balancing distribution, failover status). An agent can tell this is a status/metrics read, distinct from siblings like lmstudio_health, though it doesn't explicitly contrast with lmstudio_health.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Provides no indication of when to use this versus lmstudio_health or other monitoring tools. There are no conditions, exclusions, or named alternatives to route the agent.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

  1. 5 tool updatesv2.0.0
    • First observedlmstudio_chat
    • First observedlmstudio_embeddings
    • First observedlmstudio_health
    • First observedlmstudio_list_models
    • First observedlmstudio_pool_status

TDQS

A3.7/5.0

Scored across 5 tools

Disambiguation4/5

Each tool targets a distinct capability: chat completion, model listing, embeddings, instance health, and pool-level metrics. The only mild overlap is lmstudio_health vs lmstudio_pool_status, both of which report on instance state, but the descriptions distinguish per-instance diagnostics from aggregate load-balancing/failover metrics.

Naming Consistency5/5

All five tools use a consistent snake_case pattern with the same lmstudio_ namespace prefix followed by a clear noun/verb topic. No mixed conventions or vague verbs.

Tool Count5/5

Five tools is well-scoped for a local-model connector: one each for inference, embeddings, model discovery, instance health, and pool observability. No tool appears redundant or filler.

Completeness4/5

Core workflows (chat, embeddings, model discovery, health/pool monitoring) are covered. However, model lifecycle operations like loading/unloading models or selecting a target instance per request are absent, which could limit agent control over the daemon.

Maintenance

ActivityMaintained
ResponsivenessNo issues

Related MCP Connectors

Related MCP Servers

  • F
    license
    A
    quality
    D
    maintenance
    MCP server that connects LLM agents to a local LM Studio instance, enabling model management, OpenAI-compatible chat completions, text completions, and embeddings through a set of tools.
    9
    1
    -
  • A
    license
    Not graded
    quality
    A
    maintenance
    Enables connecting, aggregating, and routing multiple backend Model Context Protocol servers (Stdio, SSE, and Streamable HTTP) by exposing their combined tools and resources through unified SSE/HTTP endpoints or a single Stdio interface, with optional authentication and web-based admin management.
    52 npm
    MIT
  • A
    license
    Not graded
    quality
    A
    maintenance
    Aggregates multiple backend Model Context Protocol servers of Stdio, SSE, and Streamable HTTP types and exposes their combined tools and resources through a single unified SSE, Streamable HTTP, or Stdio interface with request routing and authentication. Includes an optional web admin UI for managing server connections, enabling or disabling individual tools, overriding tool names and descriptions, and live-reloading configuration.
    52 npm
    MIT