headroomlabs-ai/headroom · error · ImportError

MCP SDK not installed. Install with: pip install mcp

Error message

MCP SDK not installed. Install with: pip install mcp

What it means

The CCR MCP server class guards its constructor: if the optional 'mcp' package (or its Server class) is not importable (MCP_AVAILABLE is False / Server is None), __init__ raises ImportError telling you to pip install mcp. The MCP server only ships as an optional extra, so a plain headroom install cannot serve MCP sessions.

Source

Thrown at headroom/ccr/mcp_server.py:385

                   (for content compressed by the proxy's automatic pipeline).
    """

    def __init__(
        self,
        proxy_url: str = DEFAULT_PROXY_URL,
        check_proxy: bool = True,
    ):
        self.proxy_url = proxy_url
        self.check_proxy = check_proxy
        self._http_client: httpx.AsyncClient | None = None  # type: ignore[assignment]
        self._stats = SessionStats()
        self._local_store: Any = None  # Lazy-initialized CompressionStore
        self._compressor_initialized = False
        # File read cache: path → (content_hash, ccr_hash, line_count, token_count)
        self._file_cache: dict[str, tuple[str, str, int, int]] = {}

        if not MCP_AVAILABLE or Server is None:
            raise ImportError("MCP SDK not installed. Install with: pip install mcp")

        self.server: Server = Server("headroom")
        self._setup_handlers()

    def _get_local_store(self) -> Any:
        """Get the shared compression store singleton (lazy init).

        Returns the same instance the proxy and response_handler use so
        retrieval can see content either side compressed in-process.
        Called with no args to keep one shared config; the compress path
        passes its own per-entry ``ttl`` at store time.
        """
        if self._local_store is None:
            from headroom.cache.compression_store import get_compression_store

            self._local_store = get_compression_store()
        return self._local_store

View on GitHub (pinned to 322425c43b)

Solutions

1. Install the extra: pip install 'headroom-ai[mcp]' (or pip install mcp)
2. Verify with: python -c "import mcp; from mcp.server import Server; print('ok')"
3. Recreate/switch to the venv you actually run headroom from — extras are per-environment
4. Upgrade headroom if the mcp SDK version it requires conflicts with an existing install

Example fix

# before
server = create_ccr_mcp_server()  # ImportError: MCP SDK not installed

# after
# pip install 'headroom-ai[mcp]'
server = create_ccr_mcp_server()

try:
    from mcp.server import Server  # the exact import the guard checks
    MCP_OK = True
except ImportError:
    MCP_OK = False

if not MCP_OK:
    raise SystemExit("MCP extra missing — pip install 'headroom-ai[mcp]'")

try:
    server = create_ccr_mcp_server(...)
except ImportError as e:
    if "MCP SDK" in str(e):
        log.error("headroom[mcp] extra required for MCP serving")
        sys.exit(1)
    raise

When it happens

Trigger: Instantiating the CCR MCP session/server class (headroom.ccr.mcp_server) in an environment where 'import mcp' failed at module import time; e.g. calling create_ccr_mcp_server() without the extra installed.

Common situations: Installing bare 'headroom-ai' instead of 'headroom-ai[mcp]'; a venv where mcp was uninstalled; Python version incompatibility pulling no mcp wheel.

Related errors

• Error: MCP SDK not installed.
• Error: MCP dependencies not installed: {e}
• 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/d4050ec37332a97c. Report an issue: GitHub.