headroomlabs-ai/headroom · error · SystemExit

Error: MCP dependencies not installed: {e}

Error message

Error: MCP dependencies not installed: {e}

What it means

`headroom mcp serve` imports create_ccr_mcp_server from headroom.ccr.mcp_server; that module pulls the MCP SDK transitively. On ImportError the CLI prints the missing-dependency error with the underlying exception text and the [mcp] extra hint, then exits 1 before starting any server. It is a startup-time guard, so nothing is listening on the requested host/port when you see it.

Source

Thrown at headroom/cli/mcp.py:356

    This command is typically invoked by Claude Code via the MCP config,
    not run directly. It starts the MCP server with stdio by default or
    Streamable HTTP when requested.

    \b
    For manual testing:
        headroom mcp serve --debug
        headroom mcp serve --transport http --host 127.0.0.1 --port 8788 --path /mcp
    """
    import asyncio
    import logging

    # Check for MCP SDK
    try:
        from headroom.ccr.mcp_server import create_ccr_mcp_server
    except ImportError as e:
        click.echo(f"Error: MCP dependencies not installed: {e}", err=True)
        click.echo("Install with: pip install 'headroom-ai[mcp]'", err=True)
        raise SystemExit(1) from None

    if debug:
        logging.basicConfig(
            level=logging.DEBUG,
            format="%(asctime)s - %(name)s - %(levelname)s - %(message)s",
        )
    else:
        # Minimal logging for MCP (stdout is used for protocol)
        logging.basicConfig(
            level=logging.WARNING,
            format="%(levelname)s: %(message)s",
        )

    transport = transport.lower()

    # Use default if not specified
    effective_proxy_url = proxy_url or DEFAULT_PROXY_URL

View on GitHub (pinned to 322425c43b)

Solutions

1. pip install 'headroom-ai[mcp]' in the serving environment
2. Read the '{e}' detail — if a transitive package (e.g. anyio/starlette pin) failed, fix that pin
3. Confirm the right interpreter: `headroom --version` vs `which python` in your service unit / wrapper script
4. For systemd/docker deployments, add the extra in the image build, not at runtime

Example fix

# before
$ headroom mcp serve --transport http --port 8788
# Error: MCP dependencies not installed: ...

# after
$ pip install 'headroom-ai[mcp]'
$ headroom mcp serve --transport http --port 8788

try:
    from headroom.ccr.mcp_server import create_ccr_mcp_server  # noqa: F401
    READY = True
except ImportError as e:
    READY = False
    REASON = str(e)

if not READY:
    raise SystemExit(f"cannot serve MCP: {REASON}; pip install 'headroom-ai[mcp]'")

try:
    from headroom.ccr.mcp_server import create_ccr_mcp_server
except ImportError as e:
    logging.getLogger(__name__).critical("mcp extra missing: %s", e)
    sys.exit(1)

When it happens

Trigger: Running `headroom mcp serve [--transport http ...]` in an environment lacking the mcp package (or a broken transitive dep), causing headroom.ccr.mcp_server import to fail.

Common situations: Bare headroom-ai install used as an MCP server; venv drift after mcp was removed; pip resolver downgrading mcp below the version headroom's server module needs.

Related errors

• Error: MCP SDK not installed.
• 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/ba548563c3340be1. Report an issue: GitHub.