headroomlabs-ai/headroom · error · SystemExit

Error: MCP SDK not installed.

Error message

Error: MCP SDK not installed.

What it means

`headroom mcp install` needs the MCP SDK only to validate that MCP registration is possible; it does a bare `import mcp` first. On ImportError it prints 'Error: MCP SDK not installed.' with the install hint for the [mcp] extra and exits 1 before touching any agent config. Pure dependency guard, nothing has been modified when you see it.

Source

Thrown at headroom/cli/mcp.py:157

    \b
    By default this installs into every agent that has a registrar and is
    detected on this system (Claude Code today; Cursor / Codex / Continue /
    others added in subsequent releases). Pass ``--agent NAME`` one or more
    times to restrict the installation.

    \b
    Examples:
        headroom mcp install                            # every detected agent
        headroom mcp install --agent claude             # Claude Code only
        headroom mcp install --proxy-url http://localhost:9000
    """
    try:
        import mcp  # noqa: F401
    except ImportError:
        click.echo("Error: MCP SDK not installed.", err=True)
        click.echo("Install with: pip install 'headroom-ai[mcp]'", err=True)
        raise SystemExit(1) from None

    from headroom.mcp_registry import any_succeeded, format_results, install_everywhere

    results = install_everywhere(
        proxy_url=proxy_url,
        agents=list(agents) if agents else None,
        force=force,
    )

    if not results:
        click.echo("No agents matched the requested filter.")
        raise SystemExit(1)

    click.echo("Installing Headroom MCP server...")
    for line in format_results(
        results,
        verbose=True,
        overwrite_hint=f"headroom mcp install --proxy-url {proxy_url} --force",

View on GitHub (pinned to 322425c43b)

Solutions

1. pip install 'headroom-ai[mcp]' (equivalently pip install mcp) in the environment headroom runs from
2. Verify: python -c 'import mcp' using the same interpreter as `headroom`
3. Reinstall headroom with extras if the extra name changed across versions: pip install 'headroom-ai[mcp]' --upgrade
4. Re-run headroom mcp install after the install — no partial state was created

Example fix

# before
$ headroom mcp install
# Error: MCP SDK not installed.

# after
$ pip install 'headroom-ai[mcp]'
$ headroom mcp install

try:
    import mcp  # noqa: F401
    MCP_OK = True
except ImportError:
    MCP_OK = False

if not MCP_OK:
    raise SystemExit("pip install 'headroom-ai[mcp]' before running mcp install")

When it happens

Trigger: Running `headroom mcp install [--agent ...]` in an environment where the mcp package is not installed.

Common situations: pip install headroom-ai without extras; system Python vs venv confusion; uninstalling mcp after installing headroom.

Related errors

• Error: MCP dependencies not installed: {e}
• MCP SDK not installed. Install with: pip install mcp
• Error: Memory eval dependencies not installed.
• Error: Memory eval V2 dependencies not installed.
• Error: Proxy dependencies not installed. Run: pip install he

AI-assisted analysis of headroomlabs-ai/headroom@322425c43b (2026-08-15). Data as JSON: /api/errors/fd734e52d5680ba3. Report an issue: GitHub.