lmstudio-agent-mcp
Allows web search via DuckDuckGo (no API key required), returning titles, URLs, and snippets.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@lmstudio-agent-mcp search for Python web scraping tutorials"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
Agent MCP Server for LM Studio
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 |
| Read text files with offset/limit pagination and encoding support |
| Write or append to files, with optional parent directory creation |
| Execute shell commands with pipes, redirections, custom working directory, environment variables, and configurable timeout |
| Search the web via DuckDuckGo, Bing, Google, or Baidu (switchable), returning titles, URLs, and snippets |
| Persist a key/value memory entry with category and tags |
| Load a single memory entry by key |
| List memory entries, optionally filtered by category/tag |
| Delete a single memory entry |
| Full-text search across key, value, and tags (substring or regex) |
| Discover skills available in the configured skills directory |
| 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-mcpAfter installation, three console scripts are available:
Script | Purpose |
| Start the MCP server ( |
| Register this server with LM Studio's |
| 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.
Editable / source install — a setuptools
cmdclasshook appends anagent_mcpentry to~/.lmstudio/mcp.jsonimmediately after install.Wheel install (e.g. from PyPI) — the first time
lmstudio-agent-mcpstarts 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-scriptOther 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-mcpUsage 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_mcpFor 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 |
|
| Path to the persistent memory store |
|
| Directory scanned for user-defined skills |
|
| Set to |
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 |
| string | (required) | Absolute or relative path to the file |
| int |
| Number of lines to skip from the beginning |
| int | null |
| Maximum number of lines to return ( |
| string |
| Text encoding |
agent_write_file
Write text content to a file.
Parameter | Type | Default | Description |
| string | (required) | Absolute or relative path to the file |
| string | (required) | Text content to write |
| string |
| Text encoding |
| bool |
| If |
| bool |
| If |
agent_execute_command
Execute a terminal command.
Parameter | Type | Default | Description |
| string | (required) | Shell command to execute |
| string | null |
| Working directory (defaults to server cwd) |
| float |
| Maximum execution time in seconds (1-600) |
| object | null |
| Additional environment variables to set |
| bool |
| Execute through system shell (required for pipes/redirects) |
agent_web_search
Search the web using multiple search engines.
Parameter | Type | Default | Description |
| string | (required) | Search query (1-500 chars) |
| string |
| Search engine: |
| int |
| Maximum results to return (1-20) |
| string | null |
| Region/locale code (e.g. |
agent_memory_save
Persist a key/value memory entry to disk for cross-session recall.
Parameter | Type | Default | Description |
| string | (required) | Unique identifier (1-200 chars) |
| string | (required) | Content to remember |
| string |
| Logical bucket for filtering |
| string[] |
| Tags for retrieval filtering |
| bool |
| If |
agent_memory_load
Load a single memory entry by key.
Parameter | Type | Default | Description |
| 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 |
| string | null |
| Restrict to one category |
| string | null |
| Restrict to entries carrying this tag |
| int |
| Maximum entries to return (1-1000) |
agent_memory_delete
Delete a single memory entry.
Parameter | Type | Default | Description |
| string | (required) | Key of the entry to delete |
agent_memory_search
Full-text search across key, value, and tags.
Parameter | Type | Default | Description |
| string | (required) | Substring or regex to search for (1-500 chars) |
| bool |
| Treat the query as a regular expression |
| string | null |
| Restrict the search to one category |
| int |
| Maximum matches to return (1-200) |
agent_list_skills
Discover skills available in the configured skills directory.
Parameter | Type | Default | Description |
| string | null |
| Override the skills directory |
| string | null |
| Glob pattern to filter skill names (e.g. |
agent_run_skill
Invoke a discovered skill by name.
Parameter | Type | Default | Description |
| string | (required) | Skill name (subdirectory or filename without extension) |
| string |
| Primary input passed as the first argument |
| object |
| Additional keyword arguments forwarded to the skill |
| string | null |
| Override the skills directory |
| float |
| 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 supportedLarge 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_commandandagent_run_skill(Python/shell) can run arbitrary code
License
MIT
Available Tools
11 toolsagent_execute_commandADestructive
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_skillsARead-onlyIdempotent
Discover and list skills available in the configured skills directory.
A skill is one of:
<skills_dir>/<name>/main.py(orrun.py) with arun(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_deleteADestructiveIdempotent
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_listARead-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_loadARead-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_saveAIdempotent
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_memory_searchARead-onlyIdempotent
Search memory entries by substring or regex across key, value, and tags.
Args: query: Substring or regex to look for. use_regex: Treat the query as a regular expression. category: Restrict the search to a single category. limit: Maximum number of matches to return.
Returns: str: JSON with keys 'success', 'count', and 'matches'.
Inputs: query (required), limit, category, use_regex. Returns: result
agent_read_fileARead-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_skillADestructive
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_web_searchARead-onlyIdempotent
Search the web using the specified search engine and return results.
Supported engines: duckduckgo (default), bing, google, baidu. Each result contains a title, URL, and short snippet. No API key is required.
Args: query: Search query string. engine: Search engine to use. num_results: Maximum number of results to return. region: Optional region/locale code for search results.
Returns: str: JSON string with keys 'success', 'query', 'engine', and 'results'.
Inputs: query (required), engine, region, num_results. Returns: result
agent_write_fileADestructive
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
Scored across 11 tools
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.
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.
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.
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
Connect ChatGPT, Claude, Cursor or VS Code to your Windows PC: files, terminal, browser, apps.
Use your Mac, Windows or Linux computer from ChatGPT, Claude or Codex: files, commands, documents.
Access Pollinations models and API capabilities through agent tools.
AI Agent Utility Layer for agent safety, web monitoring, crypto research and tool discovery.
Related MCP Servers
- AlicenseBqualityDmaintenanceProvides coding agent capabilities including file operations, terminal commands, search functionality, and utility operations.2712 npm5MIT
- AlicenseAqualityDmaintenanceProvides filesystem, web search, SQLite, and system tools for AI assistants like Claude, enabling secure access to local resources and the web.6MIT
- FlicenseNot gradedqualityDmaintenanceEnables Cline + LM Studio to perform web searches, download images, fetch webpages, execute shell commands, and parse PDF files without needing any API keys.-
- AlicenseAqualityDmaintenanceProvides 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.71MIT