Lm Studio MCP Server

🚀 LM Studio MCP Server

An MCP (Model Context Protocol) server that empowers AI assistants to control LM Studio models. It enables remote management of models, including listing, loading, and unloading, through the LM Studio API.

🚀 Quick Start

The LM Studio MCP Server is an MCP server that allows AI assistants to manage LM Studio models remotely. It offers various features such as health checks, model listing, loading, and unloading through the LM Studio API.

✨ Features

• Health Check: Verify the connectivity to LM Studio.
• List Downloaded Models: View all the 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.

📦 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 Examples

Running Modes

Basic Usage

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

Advanced Usage

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"
      ]
    }
  }
}

⚠️ Important Note

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

📚 Documentation

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

🔧 Technical Details

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