Skip to main content
Glama
lmstudio-agent-mcp

lmstudio-agent-mcp

by oemoem12

Agent MCP Server for LM Studio

WARNING

Do not install 1.2.0 — it has an undeclared mcp>=1.0.0 dependency that resolves to mcp 2.0.0, which renamed FastMCP to MCPServer and broke every console script with ModuleNotFoundError: No module named 'mcp.server.fastmcp'. Use 1.2.1 or later (the mcp pin is now >=1.0.0,<2.0.0). 1.2.1 has been verified end-to-end in a fresh venv: install works, all three console scripts start, and every tool responds correctly over stdio MCP.

A lightweight MCP (Model Context Protocol) server that provides local agent capabilities for LM Studio: file I/O, terminal execution, multi-engine web search, persistent key/value memory, and a pluggable skill system.

  • 📦 PyPI 1.2.1 — pip install lmstudio-agent-mcp

  • 🔌 Auto-registers with LM Studio — no manual config editing required

  • 🛠 11 tools, ~14 kB wheel, no heavy dependencies

Features

Tool

Description

agent_read_file

Read text files with offset/limit pagination and encoding support

agent_write_file

Write or append to files, with optional parent directory creation

agent_execute_command

Execute shell commands with pipes, redirections, custom working directory, environment variables, and configurable timeout

agent_web_search

Search the web via DuckDuckGo, Bing, Google, or Baidu (switchable), returning titles, URLs, and snippets

agent_memory_save

Persist a key/value memory entry with category and tags

agent_memory_load

Load a single memory entry by key

agent_memory_list

List memory entries, optionally filtered by category/tag

agent_memory_delete

Delete a single memory entry

agent_memory_search

Full-text search across key, value, and tags (substring or regex)

agent_list_skills

Discover skills available in the configured skills directory

agent_run_skill

Invoke a discovered skill (Python, shell, or markdown)

Related MCP server: MCP Server Toolkit

Requirements

  • Python 3.10+

  • Dependencies listed in requirements.txt

Installation

pip install lmstudio-agent-mcp

After installation, three console scripts are available:

Script

Purpose

lmstudio-agent-mcp

Start the MCP server (serve is the default subcommand)

lmstudio-mcp-setup

Register this server with LM Studio's mcp.json

lmstudio-mcp-config

Print or write the LM Studio MCP config snippet

Auto-registration with LM Studio

The package registers itself with LM Studio automatically — no copy/paste required.

  1. Editable / source install — a setuptools cmdclass hook appends an agent_mcp entry to ~/.lmstudio/mcp.json immediately after install.

  2. Wheel install (e.g. from PyPI) — the first time lmstudio-agent-mcp starts it writes the entry silently. To trigger the registration right after install run:

    lmstudio-mcp-setup

The function is idempotent: re-running it is a no-op. Pass --force to overwrite an existing entry. To opt out, set the environment variable LMSTUDIO_AGENT_NO_AUTOREGISTER=1 before starting the server.

A marker file ~/.lmstudio/.lmstudio_agent_mcp_installed is written next to mcp.json so the registration is not repeated unnecessarily. The generated snippet uses the installed lmstudio-agent-mcp console script as the command so no Python interpreter path is baked in:

{
  "mcpServers": {
    "agent_mcp": {
      "command": "/home/<you>/.local/bin/lmstudio-agent-mcp"
    }
  }
}

To print or write the config snippet manually:

lmstudio-mcp-config
# with overrides:
lmstudio-mcp-config --python /path/to/python --skills-dir ~/my_skills --memory-file ~/my_memory.json
# write directly (merges into existing mcp.json if present):
lmstudio-mcp-config --write ~/.lmstudio/mcp.json
# use the python module form instead of the console script:
lmstudio-mcp-config --no-console-script

Other install methods

# editable install (development)
git clone https://github.com/oemoem12/lmstudio-agent-mcp.git
cd lmstudio-agent-mcp
pip install -e .

# npm wrapper (thin shell around the Python package)
npm install -g lmstudio-agent-mcp

Usage with LM Studio

Restart LM Studio after running lmstudio-mcp-setup. The server will appear in the MCP list as agent_mcp. The CLI also generates a JSON snippet for mcp.json automatically; if you prefer to add it by hand:

{
  "mcpServers": {
    "agent_mcp": {
      "command": "/usr/bin/python3",
      "args": ["-m", "lmstudio_agent_mcp"]
    }
  }
}

The CLI automatically detects the current Python interpreter. Use --python to override it (e.g. for a virtualenv) and --skills-dir / --memory-file to customize where the server looks for skills and where it stores memory.

Usage with Other MCP Clients

The server uses stdio transport by default. Start it directly:

python3 -m lmstudio_agent_mcp

For remote access, switch to streamable HTTP:

import lmstudio_agent_mcp
lmstudio_agent_mcp.mcp.run(transport="streamable_http", port=8000)

Configuration

The server reads the following environment variables on startup:

Variable

Default

Purpose

LMSTUDIO_AGENT_MEMORY_FILE

~/.lmstudio_agent_mcp/memory.json

Path to the persistent memory store

LMSTUDIO_AGENT_SKILLS_DIR

~/.agents/skills/

Directory scanned for user-defined skills

LMSTUDIO_AGENT_NO_AUTOREGISTER

0

Set to 1 to disable silent autoregistration on first serve

The skills directory also accepts SKILL.md (with optional scripts/, reference/, etc. siblings) in addition to main.py / run.py directories.

Tool Reference

agent_read_file

Read the contents of a text file.

Parameter

Type

Default

Description

path

string

(required)

Absolute or relative path to the file

offset

int

0

Number of lines to skip from the beginning

limit

int | null

200

Maximum number of lines to return (null = unlimited)

encoding

string

"utf-8"

Text encoding

agent_write_file

Write text content to a file.

Parameter

Type

Default

Description

path

string

(required)

Absolute or relative path to the file

content

string

(required)

Text content to write

encoding

string

"utf-8"

Text encoding

append

bool

false

If true, append instead of overwrite

create_dirs

bool

true

If true, create parent directories when missing

agent_execute_command

Execute a terminal command.

Parameter

Type

Default

Description

command

string

(required)

Shell command to execute

working_directory

string | null

null

Working directory (defaults to server cwd)

timeout

float

60.0

Maximum execution time in seconds (1-600)

env

object | null

null

Additional environment variables to set

shell

bool

true

Execute through system shell (required for pipes/redirects)

Search the web using multiple search engines.

Parameter

Type

Default

Description

query

string

(required)

Search query (1-500 chars)

engine

string

"duckduckgo"

Search engine: duckduckgo, bing, google, or baidu

num_results

int

5

Maximum results to return (1-20)

region

string | null

null

Region/locale code (e.g. wt-wt, us-en, zh-cn)

agent_memory_save

Persist a key/value memory entry to disk for cross-session recall.

Parameter

Type

Default

Description

key

string

(required)

Unique identifier (1-200 chars)

value

string

(required)

Content to remember

category

string

"general"

Logical bucket for filtering

tags

string[]

[]

Tags for retrieval filtering

overwrite

bool

true

If false, fail when key already exists

agent_memory_load

Load a single memory entry by key.

Parameter

Type

Default

Description

key

string

(required)

Key of the entry to load

agent_memory_list

List memory entries, optionally filtered by category and/or tag.

Parameter

Type

Default

Description

category

string | null

null

Restrict to one category

tag

string | null

null

Restrict to entries carrying this tag

limit

int

100

Maximum entries to return (1-1000)

agent_memory_delete

Delete a single memory entry.

Parameter

Type

Default

Description

key

string

(required)

Key of the entry to delete

Full-text search across key, value, and tags.

Parameter

Type

Default

Description

query

string

(required)

Substring or regex to search for (1-500 chars)

use_regex

bool

false

Treat the query as a regular expression

category

string | null

null

Restrict the search to one category

limit

int

20

Maximum matches to return (1-200)

agent_list_skills

Discover skills available in the configured skills directory.

Parameter

Type

Default

Description

skills_dir

string | null

null

Override the skills directory

pattern

string | null

null

Glob pattern to filter skill names (e.g. trans*)

agent_run_skill

Invoke a discovered skill by name.

Parameter

Type

Default

Description

name

string

(required)

Skill name (subdirectory or filename without extension)

input

string

""

Primary input passed as the first argument

args

object

{}

Additional keyword arguments forwarded to the skill

skills_dir

string | null

null

Override the skills directory

timeout

float

60.0

Maximum execution time in seconds (1-600)

Writing Skills

Place skills under the directory pointed to by LMSTUDIO_AGENT_SKILLS_DIR (default ~/.agents/skills/). Three skill types are supported:

Python skill (subdirectory)

skills/
└── summarize/
    ├── SKILL.md        # optional description (first paragraph is used)
    └── main.py         # must define `def run(input, **kwargs)`
# skills/summarize/main.py
def run(input: str, **kwargs) -> str:
    max_words = int(kwargs.get("max_words", 50))
    words = input.split()
    return " ".join(words[:max_words])

Python skill (single file)

# skills/translate.py
def run(input: str, **kwargs) -> str:
    target = kwargs.get("target", "zh")
    return f"[{target}] {input}"

Shell skill

# skills/count_lines.sh  (must be executable)
#!/usr/bin/env bash
echo "Lines: $(wc -l < "$1")"

The input parameter becomes $1; args become additional positional arguments.

Markdown skill

<!-- skills/cheatsheet.md -->
# Cheatsheet

Useful commands ...

A markdown skill simply returns the file contents when invoked.

Example: Memory + Skill Workflow

# 1) Save user preferences
agent_memory_save(key="user.lang", value="zh-CN", category="user", tags=["lang"])

# 2) Later, recall them
agent_memory_load(key="user.lang")

# 3) Run a custom skill
agent_run_skill(name="summarize", input="long text ...", args={"max_words": 20})

Security Notes

  • File paths are resolved to absolute paths; ~ expansion is supported

  • Large files (>10 MiB) are rejected to prevent memory exhaustion

  • Command execution has a configurable timeout (max 600s)

  • The memory file is rewritten atomically (temp file + rename) to prevent corruption

  • Do not expose this server to untrusted clients — agent_execute_command and agent_run_skill (Python/shell) can run arbitrary code

License

MIT

Available Tools

11 tools
agent_execute_commandA
Destructive

Execute a terminal command and return stdout, stderr, and exit code.

The command runs in a subprocess. By default it is executed through the system shell so that pipes, redirections, and environment variables work. Use caution with untrusted input to avoid command injection.

Args: command: Shell command to execute. working_directory: Working directory for the command. timeout: Maximum execution time in seconds. env: Additional environment variables to set or override. shell: Execute the command through the system shell.

Returns: str: JSON string with keys 'success', 'command', 'exit_code', 'stdout', 'stderr', and 'timed_out'.

Inputs: command (required), env, shell, timeout, +1 more. Returns: result

agent_list_skillsA
Read-onlyIdempotent

Discover and list skills available in the configured skills directory.

A skill is one of:

  • <skills_dir>/<name>/main.py (or run.py) with a run(input, **kwargs) function

  • <skills_dir>/<name>.py — Python skill

  • <skills_dir>/<name>.sh — Shell skill

  • <skills_dir>/<name>.md — Markdown skill (returns the file contents)

Args: skills_dir: Override the skills directory. pattern: Optional glob pattern to filter skill names.

Returns: str: JSON with keys 'success', 'skills_dir', 'count', and 'skills'.

Inputs: pattern, skills_dir. Returns: result

agent_memory_deleteA
DestructiveIdempotent

Delete a single memory entry by key.

Args: key: Key of the memory entry to delete.

Returns: str: JSON with keys 'success', 'key', and 'deleted' (bool).

Inputs: key (required). Returns: result

agent_memory_listA
Read-onlyIdempotent

List memory entries, optionally filtered by category and/or tag.

Args: category: Only return entries in this category. tag: Only return entries carrying this tag. limit: Maximum number of entries to return.

Returns: str: JSON with keys 'success', 'count', and 'entries'.

Inputs: tag, limit, category. Returns: result

agent_memory_loadA
Read-onlyIdempotent

Load a single memory entry by key.

Args: key: Key of the memory entry to load.

Returns: str: JSON with keys 'success', 'key', and the full entry payload.

Inputs: key (required). Returns: result

agent_memory_saveA
Idempotent

Persist a key/value memory entry to disk for cross-session recall.

Each entry stores: key, value, category, tags, created_at, updated_at. Memory is kept in a JSON file and is safe to read concurrently.

Args: key: Unique identifier for the entry. value: Content to remember. category: Logical bucket for the entry. tags: Optional list of tags for retrieval filtering. overwrite: If False, fail when the key already exists.

Returns: str: JSON with keys 'success', 'key', 'category', 'tags', 'operation' ('created' or 'updated').

Inputs: key (required), value (required), tags, category, +1 more. Returns: result

agent_read_fileA
Read-onlyIdempotent

Read the contents of a text file.

Returns a JSON object with the file path, requested offset/limit, and the lines that were read. Large files are capped at MAX_FILE_SIZE bytes.

Args: path: Absolute or relative path to the file. offset: Number of lines to skip from the beginning. limit: Maximum number of lines to return (null = unlimited). encoding: Text encoding to use.

Returns: str: JSON string with keys 'success', 'path', 'offset', 'limit', 'total_lines', 'truncated', and 'content'.

Inputs: path (required), limit, offset, encoding. Returns: result

agent_run_skillA
Destructive

Invoke a discovered skill by name and return its result.

Python skills are imported in-process and their run(input, **kwargs) function is called. Shell skills are executed via subprocess. Markdown skills simply return the file contents.

Args: name: Skill name. input: Primary input passed to the skill as the first argument. args: Additional keyword arguments forwarded to the skill. skills_dir: Override the skills directory. timeout: Maximum execution time in seconds.

Returns: str: JSON with keys 'success', 'name', 'type', 'stdout', 'stderr', 'exit_code', and 'timed_out'.

Inputs: name (required), args, input, timeout, +1 more. Returns: result

agent_write_fileA
Destructive

Write text content to a file, optionally creating parent directories.

Args: path: Absolute or relative path to the file. content: Text content to write. encoding: Text encoding to use. append: If True, append to the file instead of overwriting. create_dirs: If True, create parent directories when they do not exist.

Returns: str: JSON string with keys 'success', 'path', 'bytes_written', and 'operation' ('append' or 'overwrite').

Inputs: path (required), content (required), append, encoding, +1 more. Returns: result

Tool Schema Changelog

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

Loading tool schema changelog…

    TDQS

    A4.2/5.0

    Scored across 11 tools

    Disambiguation5/5

    Each tool targets a distinct action and resource: memory operations (load/save/list/delete/search) are clearly separated, file read/write are distinct, command execution, web search, and skill management (list/run) are all unique. No two tools overlap in purpose.

    Naming Consistency5/5

    All tools follow the consistent pattern agent_<verb>_<noun> (e.g., memory_load, read_file, web_search). The verb-noun structure is uniform and predictable across file, memory, and skill operations.

    Tool Count5/5

    11 tools is well within the optimal range; the server's broad scope (memory, files, commands, web, skills) justifies each tool, with no redundancy or bloat.

    Completeness4/5

    The memory subsystem has full CRUD plus search; file read/write covers typical text I/O; command execution and web search cover external interactions; skill discovery/execution is complete. Minor gaps like file delete/list exist but are not critical for the toolkit's purpose.

    Related MCP Connectors

    Related MCP Servers

    • F
      license
      Not graded
      quality
      D
      maintenance
      Enables Cline + LM Studio to perform web searches, download images, fetch webpages, execute shell commands, and parse PDF files without needing any API keys.
      -
    • A
      license
      A
      quality
      D
      maintenance
      Provides AI agents with local file-processing capabilities for token counting, RAG chunking, CSV/JSON conversion, QR generation, and more, while keeping documents private on the user's machine.
      7
      1
      MIT