Running gpt-oss-20b locally with LM Studio

Who this is for

This guide is for people who want to run a large language model on their own computer and prefer a graphical interface. By the end you should be able to download and chat with gpt-oss-20b in LM Studio, call its local API from Python, and see how MCP tools are connected to it.

What LM Studio is

LM Studio is an application for running large language models locally. Compared with Ollama, it offers a richer user interface and is easier to get started with for people who want to work visually^[1]. LM Studio also suits deployments and use without a network connection^[1]. Running models locally gives privacy, room for customization and the option of offline use^[1]. It runs on Windows, macOS and Linux, and the download page is lmstudio.ai/download^[2]. For people who only want to try a model, everything can be done in one window without memorising commands; for developers, the local server offers an OpenAI-style interface, so existing client code needs little change^[1].

Preparation

Download and install the version for your system from lmstudio.ai^[2]. The model used here is gpt-oss-20b. LM Studio's model search recommends models based on your hardware^[1]. The command line can also download the 20B model, and a 120B variant is available as well^[1].

Steps

1. Install LM Studio and search for gpt-oss-20b in the app to download it. If the network is poor, download the model files from a source such as ModelScope and place them in LM Studio's model library^[1].
2. Download from the command line (optional)^[1]:

# For 20B
lms get openai/gpt-oss-20b
# or for 120B
lms get openai/gpt-oss-120b

1. After the model is loaded, chat with it in LM Studio's chat interface^[1]. You can also chat from the terminal^[1]:

lms chat openai/gpt-oss-20b #注意第一次运行之后才能使用lmx命令

This command works after LM Studio has been run at least once^[1].

1. Start the local server and call the model through the API. After you start LM Studio's local server, point the OpenAI client's base_url at http://localhost:1234/v1. LM Studio does not require an API key, so the example uses the placeholder not-needed^[1]:

from openai import OpenAI
 
client = OpenAI(
    base_url="http://localhost:1234/v1",
    api_key="not-needed"  # LM Studio does not require an API key
)
 
result = client.chat.completions.create(
    model="openai/gpt-oss-20b",
    messages=[
        {"role": "system", "content": "You are a helpful assistant."},
        {"role": "user", "content": "Explain what MXFP4 quantization is."}
    ]
)
 
print(result.choices[0].message.content)

The model field must be openai/gpt-oss-20b^[1]. The reply text is in result.choices[0].message.content^[1].

Connecting MCP tools

LM Studio is an MCP client. You can connect MCP servers to give the gpt-oss model external tools^[1][3]. The MCP configuration file is at ~/.lmstudio/mcp.json^[1].

To define tools directly in Python, install LM Studio's Python SDK with uv pip install lmstudio or pip install lmstudio^[1][4]:

uv pip install lmstudio

The example's tool is an ordinary Python function, create_file(name, content), which creates a file on the local machine^[1][5]. It never overwrites an existing file and returns an error message when the name is taken^[1]:

def create_file(name: str, content: str):
    """创建指定名称和内容的文件。
    
    Args:
        name: 文件名（支持相对路径和绝对路径）
        content: 文件内容
        
    Returns:
        操作结果的描述信息
    """
    dest_path = Path(name)
    if dest_path.exists():
        return "错误：文件已存在，无法覆盖。"
    try:
        dest_path.write_text(content, encoding="utf-8")
    except Exception as exc:
        return f"错误：文件创建失败 - {exc!r}"
    return f"文件 '{name}' 创建成功。"

Next, load the model with lms.llm and create a chat with a system prompt using lms.Chat^[1]:

model = lms.llm("openai/gpt-oss-20b")  # 加载OpenAI GPT-OSS 20B模型
chat = lms.Chat("你是一个运行在用户计算机上的智能助手，可以帮助用户完成各种任务。")

model.act() receives the chat, the tool list and the callbacks. The model alternates between tool calls and reasoning until the task is finished^[1]:

    model.act(
        chat,                           # 聊天上下文
        [create_file],                  # 可用的工具函数列表
        on_message=chat.append,         # 将完整响应添加到聊天历史
        on_prediction_fragment=print_fragment,  # 流式输出回调
    )

The callback print_fragment prints generated text as it arrives, which gives streaming output^[1]. The example program exits when the user enters an empty line^[1]. More on tool definitions is in the official documentation^[5].

Common problems and next steps

The steps in this guide cover four stages: download, load, call and MCP. If the lms command is not found in the terminal, start LM Studio once and try again^[1]. For MCP setup and the rest of the SDK, use the official LM Studio documentation at lmstudio.ai/docs^[3][4].

Adapted from the tutorial "03-gpt-oss-20b lmstudio 本地部署调用" in Datawhale's open-source project self-llm^[1], released under the Apache-2.0 License.