LM Studio

https://lmstudio.ai/docs/app
Admin
LM Studio is a desktop application that enables users to download, run, and interact with various...
Tokens:11,006
Snippets:146
Trust Score:10
Update:8 months ago
Show doc for...
Tokens:
Raw
### MCP Server Installation Deeplink

Source: https://lmstudio.ai/docs/app/mcp/deeplink

This section details the process of generating and using deeplinks to install MCP servers within LM Studio. It includes an example of the configuration JSON and the resulting deeplink format.

```APIDOC
## Generate MCP Install Deeplink

### Description
Use the MCP link generator to create a deeplink that allows one-click installation of MCP servers in LM Studio. This feature is available starting from LM Studio version 0.3.17 (10).

### Method
N/A (This describes a deeplink format, not a direct API call)

### Endpoint
`lmstudio://add_mcp`

### Parameters
#### Query Parameters
- **name** (string) - Required - The name of the MCP server to install.
- **config** (string) - Required - A Base64 encoded JSON configuration for the MCP server.

### Request Example (Configuration JSON)
```json
{
  "hf-mcp-server": {
    "url": "https://huggingface.co/mcp",
    "headers": {
      "Authorization": "Bearer <YOUR_HF_TOKEN>"
    }
  }
}
```

### Deeplink Example
`lmstudio://add_mcp?name=hf-mcp-server&config=eyJ1cmwiOiJodHRwczovL2h1Z2dpbmdmYWNlLmNvL21jcCIsImhlYWRlcnMiOnsiQXV0aG9yaXphdGlvbiI6IkJlYXJlciA8WU9VUl9IRl9UT0tFTj4ifX0%3D`

### Response
#### Success Response
Upon clicking the deeplink, LM Studio will open and attempt to install the specified MCP server. No explicit API response is returned in the browser context.
```

--------------------------------

### Complete model.yaml Example

Source: https://lmstudio.ai/docs/app/modelyaml

A comprehensive example demonstrating the integration of all core fields: model identifier, base model sources, metadata overrides, configuration for operation and load, and custom fields.

```yaml
# model.yaml is an open standard for defining cross-platform, composable AI models
# Learn more at https://modelyaml.org
model: qwen/qwen3-8b
base:
  - key: lmstudio-community/qwen3-8b-gguf
    sources:
      - type: huggingface
        user: lmstudio-community
        repo: Qwen3-8B-GGUF
  - key: lmstudio-community/qwen3-8b-mlx-4bit
    sources:
      - type: huggingface
        user: lmstudio-community
        repo: Qwen3-8B-MLX-4bit
  - key: lmstudio-community/qwen3-8b-mlx-8bit
    sources:
      - type: huggingface
        user: lmstudio-community
        repo: Qwen3-8B-MLX-8bit
metadataOverrides:
  domain: llm
  architectures:
    - qwen3
  compatibilityTypes:
    - gguf
    - safetensors
  paramsStrings:
    - 8B
  minMemoryUsageBytes: 4600000000
  contextLengths:
    - 40960
  vision: false
  reasoning: true
  trainedForToolUse: true
config:
  operation:
    fields:
      - key: llm.prediction.topKSampling
        value: 20
      - key: llm.prediction.minPSampling
        value:
          checked: true
          value: 0
customFields:
  - key: enableThinking
    displayName: Enable Thinking
    description: Controls whether the model will think before replying
    type: boolean
    defaultValue: true
    effects:
      - type: setJinjaVariable
        variable: enable_thinking
```

--------------------------------

### Generate MCP Install Deeplink for LM Studio

Source: https://lmstudio.ai/docs/app/mcp/deeplink

This section provides a tool to generate deeplinks for adding MCP servers to LM Studio. Users input their MCP JSON configuration, and the tool creates a clickable link that initiates the installation process within LM Studio.

```lms_mcp_deep_link_generator

```

--------------------------------

### Add MCP Server Deeplink

Source: https://lmstudio.ai/docs/app/plugins/mcp/deeplink

LM Studio allows users to install MCP servers with a single click using a custom deeplink. This feature enables easy integration of external model servers.

```APIDOC
## POST /lmstudio://add_mcp

### Description
This endpoint allows for the installation of Model Context Protocol (MCP) servers into LM Studio via a deeplink.

### Method
GET (via deeplink)

### Endpoint
lmstudio://add_mcp

### Query Parameters
- **name** (string) - Required - The name of the MCP server to install.
- **config** (string) - Required - Base64 encoded JSON configuration for the MCP server.

### Request Example
```
lmSTUDIO://ADD_MCP?NAME=HF-MCP-SERVER&CONFIG=EYJ1cmwiOiJodHRwczovL2h1Z2dpbmdmYWNlLmNvL21jcCIsImhlYWRlcnMiOnsiQXV0aG9yaXphdGlvbiI6IkJlYXJlciA8WU9VUl9IRl9UT0tFTj4ifX0%3D
```

### Response
#### Success Response (200)
LM Studio will open and attempt to install the specified MCP server.

#### Response Example
(No direct response body, action is performed by the LM Studio application.)
```

--------------------------------

### LM Studio MCP Deeplink Parameters

Source: https://lmstudio.ai/docs/app/mcp/deeplink

Defines the parameters used in the LM Studio MCP deeplink. It outlines the protocol scheme, the action path, and query parameters for specifying the server name and its configuration.

```lms_params
- name: "lmstudio://"
  type: "protocol"
  description: "The protocol scheme to open LM Studio"
- name: "add_mcp"
  type: "path"
  description: "The action to install an MCP server"
- name: "name"
  type: "query parameter"
  description: "The name of the MCP server to install"
- name: "config"
  type: "query parameter"
  description: "Base64 encoded JSON configuration for the MCP server"
```

--------------------------------

### Generate MCP Install Link Configuration (JSON)

Source: https://lmstudio.ai/docs/app/plugins/mcp/deeplink

This JSON object represents the configuration for an MCP server, including its URL and any necessary headers like authorization tokens. This is used to generate a deeplink for adding the server to LM Studio.

```json
{
  "hf-mcp-server": {
    "url": "https://huggingface.co/mcp",
    "headers": {
      "Authorization": "Bearer <YOUR_HF_TOKEN>"
    }
  }
}
```

--------------------------------

### Download a Model from LM Studio Hub

Source: https://lmstudio.ai/docs/app/modelyaml/publish

Retrieves a model that has been published to the LM Studio Hub. Users can download models using the `lms get` command followed by the model's identifier, typically in the format `username/model-name`.

```shell
lms get my-user/my-model
```

--------------------------------

### LM Studio MCP Server Warning

Source: https://lmstudio.ai/docs/app/mcp

This code snippet is a warning message for LM Studio users regarding the potential risks of installing MCP servers from untrusted sources. It highlights that some servers can execute arbitrary code, access local files, and use network connections.

```lms_warning
Some MCP servers can run arbitrary code, access your local files, and use your network connection. Always be cautious when installing and using MCP servers. If you don't trust the source, don't install it.
```

--------------------------------

### Configure Runtime Settings in model.yaml

Source: https://lmstudio.ai/docs/app/modelyaml

The 'config' field enables baking in default runtime settings for both inference ('operation') and loading ('load') time. This works similarly to per-model defaults in LM Studio.

```yaml
config:
  operation:
    fields:
      - key: llm.prediction.topKSampling
        value: 20
      - key: llm.prediction.temperature
        value: 0.7
  load:
    fields:
      - key: llm.load.contextLength
        value: 42690
```

--------------------------------

### Import GGUF Model with `lms import` (Bash)

Source: https://lmstudio.ai/docs/app/advanced/import-model

This command initiates the experimental import process for a GGUF model file downloaded outside of LM Studio. It requires the path to the GGUF file and follows an interactive prompt to complete the import.

```bash
lms import <path/to/model.gguf>
```

--------------------------------

### LM Studio Expected Models Directory Structure (XML)

Source: https://lmstudio.ai/docs/app/advanced/import-model

Illustrates the standard directory hierarchy that LM Studio expects for organizing downloaded models. This structure helps LM Studio locate and manage models, mirroring Hugging Face's organization.

```xml
~/.lmstudio/models/
└── publisher/
    └── model/
        └── model-file.gguf
```

```xml
~/.lmstudio/models/
└── infra-ai/
    └── ocelot-v1/
        └── ocelot-v1-instruct-q4_0.gguf
```

--------------------------------

### Sign in to LM Studio Hub CLI

Source: https://lmstudio.ai/docs/app/modelyaml/publish

Authenticates your command-line interface with the LM Studio Hub. After running this command, you will be prompted with an authentication URL. Approving access saves a session token locally, enabling you to publish models.

```shell
lms login
```

--------------------------------

### Specify Base Model Sources in model.yaml

Source: https://lmstudio.ai/docs/app/modelyaml

The 'base' field defines the concrete model files or other virtual models that a given model can resolve to. Each entry has a unique 'key' and one or more 'sources' (e.g., from Hugging Face) from which the file can be fetched.

```yaml
model: qwen/qwen3-8b
base:
  - key: lmstudio-community/qwen3-8b-gguf
    sources:
      - type: huggingface
        user: lmstudio-community
        repo: Qwen3-8B-GGUF
  - key: lmstudio-community/qwen3-8b-mlx-4bit
    sources:
      - type: huggingface
        user: lmstudio-community
        repo: Qwen3-8B-MLX-4bit
  - key: lmstudio-community/qwen3-8b-mlx-8bit
    sources:
      - type: huggingface
        user: lmstudio-community
        repo: Qwen3-8B-MLX-8bit
```

--------------------------------

### Clone a Model using LM Studio CLI

Source: https://lmstudio.ai/docs/app/modelyaml/publish

Clones an existing model from the LM Studio Hub to your local machine. This action downloads metadata files like `model.yaml` and `README`, but not the model weights themselves. It's the first step to modifying and republishing a model.

```shell
lms clone qwen/qwen3-8b
```

--------------------------------

### Configure Hugging Face MCP Server in LM Studio

Source: https://lmstudio.ai/docs/app/plugins/mcp

This JSON configuration allows LM Studio to connect to the Hugging Face MCP server. It requires users to replace a placeholder with their actual Hugging Face API token for authentication. Ensure the token is kept secure.

```json
{
  "mcpServers": {
    "hf-mcp-server": {
      "url": "https://huggingface.co/mcp",
      "headers": {
        "Authorization": "Bearer <YOUR_HF_TOKEN>"
      }
    }
  }
}
```

--------------------------------

### LM Studio MCP Server Deeplink Format

Source: https://lmstudio.ai/docs/app/plugins/mcp/deeplink

This is the deeplink format used to add an MCP server to LM Studio. It includes the protocol, action, server name, and a Base64 encoded JSON configuration.

```url
lmstudio://add_mcp?name=hf-mcp-server&config=eyJ1cmwiOiJodHRwczovL2h1Z2dpbmdmYWNlLmNvL21jcCIsImhlYWRlcnMiOnsiQXV0aG9yaXphdGlvbiI6IkJlYXJlciA8WU9VUl9IRl9UT0tFTj4ifX0%3D
```

--------------------------------

### Publish a Model to LM Studio Hub

Source: https://lmstudio.ai/docs/app/modelyaml/publish

Packages and uploads your local model metadata (from `model.yaml`) to the LM Studio Hub. This command requires you to be authenticated and in the directory containing your `model.yaml`. It returns a revision number for the newly published version.

```shell
lms push
```

--------------------------------

### Modify Model Publisher in model.yaml

Source: https://lmstudio.ai/docs/app/modelyaml/publish

Demonstrates how to change the publisher of a model in the `model.yaml` file. This is necessary when preparing to push a cloned model under your own user or organization account. The change is applied using a diff format.

```diff
- model: qwen/qwen3-8b
+ model: your-user-here/qwen3-8b
base:
  - key: lmstudio-community/qwen3-8b-gguf
    sources:
# ... the rest of the file
```

--------------------------------

### Define Custom Fields in model.yaml

Source: https://lmstudio.ai/docs/app/modelyaml

The 'customFields' section allows for defining model-specific custom fields, including their display name, description, type, default value, and effects (e.g., setting Jinja variables).

```yaml
customFields:
  - key: enableThinking
    displayName: Enable Thinking
    description: Controls whether the model will think before replying
    type: boolean
    defaultValue: true
    effects:
      - type: setJinjaVariable
        variable: enable_thinking
```

--------------------------------

### Show Conversations Folder Path - Mac/Linux

Source: https://lmstudio.ai/docs/app/basics/chat

Displays the file system path where LM Studio stores conversation data on macOS and Linux systems. This path is typically located in the user's home directory.

```shell
~/.lmstudio/conversations/
```

--------------------------------

### Show Conversations Folder Path - Windows

Source: https://lmstudio.ai/docs/app/basics/chat

Displays the file system path where LM Studio stores conversation data on Windows systems. This path is located within the user's profile directory.

```powershell
%USERPROFILE%\.lmstudio\conversations
```

--------------------------------

### Override Model Metadata during Publish

Source: https://lmstudio.ai/docs/app/modelyaml/publish

Allows you to modify specific fields of your model's metadata at the time of publishing without directly editing the `model.yaml` file. This is useful for quick updates to fields like the description.

```shell
lms push --overrides '{"description": "Qwen 3 8B model"}'
```

--------------------------------

### Define Model Identifier in model.yaml

Source: https://lmstudio.ai/docs/app/modelyaml

The 'model' field specifies the canonical identifier for an AI model, typically in a 'publisher/model' format. This is a core field required in any model.yaml file.

```yaml
model: qwen/qwen3-8b
```

--------------------------------

### Override Model Metadata in model.yaml

Source: https://lmstudio.ai/docs/app/modelyaml

The 'metadataOverrides' field allows for modifying metadata associated with a base model. This is primarily for presentation purposes in catalogs or search interfaces and does not affect the model's functional behavior.

```yaml
metadataOverrides:
  domain: llm
  architectures:
    - qwen3
  compatibilityTypes:
    - gguf
    - safetensors
  paramsStrings:
    - 8B
  minMemoryUsageBytes: 4600000000
  contextLengths:
    - 40960
  vision: false
  reasoning: true
  trainedForToolUse: true
```
Tokens:
Raw