simplemcp-framework 2.1.7

A Docker-powered MCP server framework — extend with drop-in kit files and connect to Claude Desktop, LM Studio, OpenWebUI, and more.

SimpleMCP V2

A Docker-powered MCP-compatible tool server you extend with drop-in kit files — no server code to touch, no venvs to manage. Drop a _kit.py file in, install it with one command, and it's live.

How it works

• CLI (simplemcp): Manages the full lifecycle — install kits, start/stop/restart/rebuild the server, configure client integrations.
• Docker container: The server runs in an isolated container built from a bundled Dockerfile. Built automatically on first start.
• Kits (~/.simplemcp/kits/): Each kit is a plain Python file with @tool-decorated functions and three metadata fields. The container mounts this directory as a volume — kits are live without rebuilding.
• bootstrap.py: Runs inside the container on every start. AST-parses each kit's requirements list and installs anything missing via uv pip into a persistent volume. Execs the real server when done.
• server.py: FastAPI server inside the container. Auto-discovers all kits. Always speaks both SimpleMCP protocol and MCP JSON-RPC on the same port — no mode flag needed.
• Registry (utils/registry.py): The @tool decorator registers functions into a global dict. Type hints are scraped to build JSON Schema for each tool's I/O automatically.
• stdio_shim.py: Thin bridge that translates MCP JSON-RPC from stdin to the already-running container's HTTP API. The container must already be running via simplemcp start. One shim process per kit entry in the client config, all sharing the same container.
• Config (~/.simplemcp/config.json): Tracks installed kits, the running port, and container ID. Written and read exclusively by the CLI.

Kit anatomy

# my_kit.py
from utils import tool

kit_name        = "My Tools"
kit_description = "What this kit does."
requirements    = ["requests", "some-package"]

@tool
def do_something(query: str, limit: int = 10):
    """Does something cool with a query."""
    return {"result": "stuff"}

• kit_name and kit_description are displayed by the protocol and simplemcp list.
• requirements is read by bootstrap.py via AST — no import needed. Missing packages are installed on container start, or immediately into a live container on simplemcp install.
• @tool is the only import required. Type hints are mandatory — they build the JSON Schema. Docstrings become the tool description shown to the model.

Server protocol

One container, one port, both protocols always running:

SimpleMCP protocol:

Endpoint	Method	Description
/list_kits	GET	All installed kit names
/inspect_kit	POST {"kit": "Name"}	Kit metadata
/list_tools_in_kit	POST {"kit": "Name"}	Full tool schemas for a kit
/inspect_tool	POST {"tool": "fn_name"}	Schema for a single tool
/run_tool	POST {"tool": "fn_name", "arguments": {...}}	Execute a tool

MCP protocol (JSON-RPC 2.0):

Endpoint	Method	Description
/mcp	POST	initialize, tools/list, tools/call
/mcp	GET	SSE keepalive

The /mcp endpoint accepts an optional X-SimpleMCP-Kit header to scope tool listings and calls to a single kit — used by the stdio shim.

stdio mode

simplemcp start stdio [kit_name] runs a shim process that bridges MCP JSON-RPC from stdin to the already-running container. The container must already be running.

• No per-connection container spawning — zero overhead per client connect
• Multiple shim processes share the same container
• Scope to a single kit with simplemcp start stdio <kit_stem>, or leave blank for all kits

CLI reference

simplemcp install <path/to/kit.py>              Install a kit
simplemcp remove <kit_name>                     Remove a kit
simplemcp start                                 Start the server
simplemcp start --verbose                       Start with full log output
simplemcp start stdio                           Start stdio shim (all kits)
simplemcp start stdio <kit_name>                Start stdio shim (single kit)
simplemcp stop                                  Stop the server
simplemcp restart                               Restart the server
simplemcp rebuild                               Rebuild the Docker image and restart
simplemcp rebuild --verbose                     Rebuild with full log output
simplemcp list                                  List installed kits and status
simplemcp compat claude                         Write kit entries to Claude Desktop config
simplemcp compat lmstudio                       Write kit entries to LM Studio config
simplemcp compat openwebui <url> <api_key>      Register kits with OpenWebUI

Setup

pip install simplemcp

Docker is the only other dependency. On Linux, simplemcp will attempt to install Docker automatically if missing and will fix docker group permissions with a single sudo call if needed.

simplemcp start

The Docker image builds automatically on first start. Kit dependencies are cached in ~/.simplemcp/packages/ so subsequent starts are fast.

Adding a kit

simplemcp install my_kit.py

If the server is already running, the kit is hot-reloaded immediately — no restart needed.

Client integrations

Claude Desktop

simplemcp compat claude

Writes a mcpServers entry for each installed kit to claude_desktop_config.json (path is OS-aware). Removes stale entries for uninstalled kits. Restart Claude Desktop after.

Manual config example:

{
  "mcpServers": {
    "Web Kit V2": {
      "command": "simplemcp",
      "args": ["start", "stdio", "web_kit"]
    },
    "Gotify": {
      "command": "simplemcp",
      "args": ["start", "stdio", "gotify_kit"],
      "env": {
        "GOTIFY_URL": "http://localhost:80",
        "GOTIFY_TOKEN": "your-token"
      }
    }
  }
}

LM Studio

simplemcp compat lmstudio

Same format as Claude Desktop, written to ~/.lmstudio/mcp.json. Restart LM Studio after.

OpenWebUI

simplemcp compat openwebui https://your-instance:port sk-your-api-key

Hits POST /api/v1/configs/tool_servers directly — no manual UI steps. Existing non-SimpleMCP tool server entries are preserved. Generate an API key under your OpenWebUI profile → Settings → Account → API Keys (enable API keys in Admin Panel → Settings → General first).

Environment variables

Kit config is passed via environment variables — either in the shell before simplemcp start, or in the env block of a client config entry. The host environment is forwarded into the container automatically (OS-specific vars like PATH are excluded). Any localhost or 127.0.0.1 references in env vars are automatically rewritten to host.docker.internal so kit code can reach host services from inside the container.