STDIO Mode

7 min

STDIO mode runs the Litmus MCP server as a local child process of an MCP client. It is the only way to use Claude Desktop (which does not speak SSE) and is convenient for local development.

STDIO mode is not available from the published Docker image. You need to clone the repository and run the Python process directly.

1. Clone

git clone https://github.com/litmusautomation/litmus-mcp-server.git
cd litmus-mcp-server

2. Enable STDIO

Edit src/config.py so that:

ENABLE_STDIO = os.getenv("ENABLE_STDIO", "true").lower() in ("true", "1", "yes")

Defaulting to true means the server runs in STDIO mode unless ENABLE_STDIO=false is passed at launch.

3. Install dependencies

Using uv:

uv sync

Using pip in a venv:

python -m venv .venv
. .venv/bin/activate
pip install -e .

4. Run the server

# uv
uv run python3 src/server.py

# plain Python
python3 src/server.py

You should see Starting Litmus MCP Server in STDIO mode in the log. The process now waits for an MCP client on stdin / stdout.

5. Wire it into an MCP client

For Claude Desktop, see Claude Desktop.

For any other STDIO-capable MCP client, the pattern is:

{
  "mcpServers": {
    "litmus-mcp-server": {
      "command": "/path/to/.venv/bin/python3",
      "args": [
        "/absolute/path/to/litmus-mcp-server/src/server.py"
      ],
      "env": {
        "PYTHONPATH": "/absolute/path/to/litmus-mcp-server/src",
        "EDGE_URL": "https://<LITMUSEDGE_IP>",
        "EDGE_API_CLIENT_ID": "<oauth2_client_id>",
        "EDGE_API_CLIENT_SECRET": "<oauth2_client_secret>",
        "NATS_SOURCE": "<LITMUSEDGE_IP>",
        "NATS_PORT": "4222",
        "NATS_USER": "<access_token_username>",
        "NATS_PASSWORD": "<access_token_from_litmusedge>",
        "INFLUX_HOST": "<LITMUSEDGE_IP>",
        "INFLUX_PORT": "8086",
        "INFLUX_DB_NAME": "tsdata",
        "INFLUX_USERNAME": "<datahub_username>",
        "INFLUX_PASSWORD": "<datahub_password>"
      }
    }
  }
}

STDIO mode reads the same credentials as SSE mode, but from process environment variables instead of HTTP headers. See Headers Reference for what each one does.

Notes

For dev work that bridges differing MCP library versions (e.g., npx @modelcontextprotocol/inspector vs litmus-mcp-server), point command at the project's venv Python so you don't pick up system-wide MCP installs. See claude_desktop_config_venv.example.json in the repo for a ready-to-edit template.

Only one MCP client can attach to a given STDIO server process at a time.

For shared or multi-user setups, use Docker SSE mode instead. See Docker.