Running the Server

Clean is a stdio MCP server. It speaks the Model Context Protocol over stdin/stdout — there is no HTTP port, no web framework, and nothing to run under uvicorn/gunicorn. In normal use your MCP client (Claude Code, Cursor, …) launches the process for you based on its config; you don't start it by hand.

Launching manually

For debugging — or just to confirm it boots — use either equivalent command:

# Module form
python -m clean.local.mcp_server
 
# Console script (installed by `pip install -e ".[dev]"`)
clean

The process then waits silently for an MCP client to connect over stdin/stdout. That silence is expected — it's not a web server and won't print a URL.

Inspecting it interactively

To talk to the server by hand, use the MCP Inspector:

npx @modelcontextprotocol/inspector python -m clean.local.mcp_server

Pin a default repo

Pass --repo owner/repo so search_code targets that repo without callers specifying it each time:

python -m clean.local.mcp_server --repo facebook/react

When set, searches that omit repo use this default automatically, inheriting the indexed branch.

Wire it into a client

The canonical project-scoped config is a .mcp.json next to your code:

{
  "mcpServers": {
    "clean": {
      "command": "python",
      "args": ["-m", "clean.local.mcp_server"]
    }
  }
}

Or register it globally via your agent's CLI:

# Claude Code
claude mcp add clean -- python -m clean.local.mcp_server
 
# Codex
codex mcp add clean -- python -m clean.local.mcp_server

See Connect your agents for per-agent file locations.