LM Studio MCP Server

An MCP (Model Context Protocol) server that provides AI assistants with control over LM Studio models. This server enables remote model management including listing, loading, and unloading models through the LM Studio API.

Features

• Health Check: Verify connectivity to LM Studio
• List Downloaded Models: View all LLM models available in your LM Studio library
• List Loaded Models: See which models are currently loaded in memory
• Load Models: Load models into memory with configurable parameters
• Unload Models: Remove specific model instances from memory
• Get Model Info: Retrieve detailed information about loaded models

Prerequisites

• Node.js 18.0.0 or higher
• LM Studio running with the local server enabled

Installation

# Clone the repository
git clone <repository-url>
cd lm-studio-mcp-server

# Install dependencies
npm install

Configuration

The server connects to LM Studio using environment variables:

Usage

Running Modes

Development (uses tsx for TypeScript execution):

npm start
# or with file watching
npm run dev

Production (uses compiled JavaScript):

npm run build
npm run start:prod

Docker:

# Pull the published image
docker pull portertech/lm-studio-mcp-server:latest

# Run (connects to LM Studio on host machine)
docker run -i --rm portertech/lm-studio-mcp-server:latest

# Run with custom LM Studio host
docker run -i --rm \
  -e LMSTUDIO_HOST=192.168.1.100 \
  -e LMSTUDIO_PORT=1234 \
  portertech/lm-studio-mcp-server:latest

MCP Client Configuration

Claude

Add to your claude_desktop_config.json:

Using npx (recommended for installed packages):

{
  "mcpServers": {
    "lmstudio": {
      "command": "npx",
      "args": ["@portertech/lm-studio-mcp-server"],
      "env": {
        "LMSTUDIO_HOST": "127.0.0.1",
        "LMSTUDIO_PORT": "1234"
      }
    }
  }
}

Using local development:

{
  "mcpServers": {
    "lmstudio": {
      "command": "npx",
      "args": ["tsx", "/path/to/lm-studio-mcp-server/src/index.ts"],
      "env": {
        "LMSTUDIO_HOST": "127.0.0.1",
        "LMSTUDIO_PORT": "1234"
      }
    }
  }
}

Using Docker:

{
  "mcpServers": {
    "lmstudio": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "-e",
        "LMSTUDIO_HOST=127.0.0.1",
        "-e",
        "LMSTUDIO_PORT=1234",
        "portertech/lm-studio-mcp-server:latest"
      ]
    }
  }
}

Note: For Docker on macOS/Windows connecting to LM Studio on the host machine, use LMSTUDIO_HOST=host.docker.internal.

Available Tools

All tools return a consistent response envelope:

{
  success: boolean;
  message: string;
  data?: T;           // Present on success
  error?: {           // Present on failure
    code: string;
    message: string;
  };
}

Error Codes

health_check

Check connectivity to LM Studio server.

Parameters: None

Returns: Connection status and base URL

list_models

List all downloaded LLM models available in LM Studio.

Parameters: None

Returns: Array of model info objects with:

• modelKey: Model identifier for loading
• path: Relative path to the model
• displayName: Human-readable model name
• sizeBytes: Size in bytes
• architecture: Model architecture (if available)
• quantization: Quantization type (if available)

list_loaded_models

List all currently loaded models in memory.

Parameters: None

Returns: Array of loaded model info with:

• identifier: Instance identifier
• modelKey: Model key
• path: Model path
• displayName: Human-readable name
• sizeBytes: Size in bytes
• vision: Whether model supports vision
• trainedForToolUse: Whether model was trained for tool use

load_model

Load a model into memory.

Parameters:

• model (required): Model key to load (e.g., llama-3.2-3b-instruct)
• identifier (optional): Custom identifier for the loaded instance
• contextLength (optional): Context window size in tokens (minimum: 1)
• evalBatchSize (optional): Batch size for token processing (minimum: 1)

Returns: Success status with loaded model details (identifier, modelKey, path)

unload_model

Unload a model from memory.

Parameters:

• identifier (required): Identifier of the loaded model to unload

Returns: Success status

get_model_info

Get detailed information about a loaded model.

Parameters:

• identifier (required): Identifier of the loaded model

Returns: Model details including identifier, modelKey, path, displayName, sizeBytes, contextLength

Development

# Build the project
npm run build

# Run in development mode with auto-reload
npm run dev

# Type check without emitting
npm run typecheck

# Run tests
npm test

# Lint
npm run lint

# Format
npm run format:check
npm run format

Release Process

The project includes a make release command for automated releases:

# Create a new release (runs CI, sets version, commits, tags, publishes to npm and Docker Hub)
make release VERSION=<version>

# Example:
make release VERSION=1.0.5

This runs the full release pipeline:

1. CI checks (lint, typecheck, test)
2. Sets version in package.json
3. Commits the version bump
4. Creates an annotated git tag (v<version>)
5. Publishes to npm
6. Builds and pushes Docker images to Docker Hub

Project Structure

src/
├── index.ts              # MCP server entry point
├── client.ts             # LM Studio client wrapper
├── types.ts              # Shared types and result helpers
└── tools/
    ├── index.ts          # Tool exports
    ├── health-check.ts   # Health check tool
    ├── list-models.ts    # List downloaded models
    ├── list-loaded-models.ts
    ├── load-model.ts
    ├── unload-model.ts
    └── get-model-info.ts

Architecture

• Consistent Results: All tools return the same ToolResult<T> envelope
• Safe Wrappers: Tool handlers are wrapped to catch exceptions and return error payloads
• Lazy Config: Environment variables are read at runtime, not module load
• Singleton Client: Single LM Studio client instance is reused

License

ISC