NousResearch/hermes-agent · error · ImportError

hermes-tools MCP server requires the 'mcp' package: {exc}

Error message

hermes-tools MCP server requires the 'mcp' package: {exc}

What it means

ImportError from _build_server() in agent/transports/hermes_tools_mcp_server.py:161. The module is deliberately importable without the 'mcp' package (lazy import), but actually building the FastMCP server requires mcp.server.fastmcp.FastMCP; if the package is missing or broken, this clear install-hint error is raised instead of a NameError at import time.

Source

Thrown at agent/transports/hermes_tools_mcp_server.py:161

    "kanban_list",
    # NOTE: kanban_create / kanban_unblock / kanban_link are orchestrator-
    # only — the kanban tool gates them on HERMES_KANBAN_TASK being unset.
    # They're exposed here for orchestrator agents running on the codex
    # runtime that need to dispatch new tasks.
    "kanban_create",
    "kanban_unblock",
    "kanban_link",
)


def _build_server() -> Any:
    """Create the FastMCP server with Hermes tools attached. Lazy imports
    so the module can be imported without the mcp package installed
    (we degrade to a clear error only when actually run)."""
    try:
        from mcp.server.fastmcp import FastMCP
    except ImportError as exc:  # pragma: no cover - install hint
        raise ImportError(
            f"hermes-tools MCP server requires the 'mcp' package: {exc}"
        ) from exc

    # Discover Hermes tools so dispatch works.
    from model_tools import (
        get_tool_definitions,
        handle_function_call,
    )

    mcp = FastMCP(
        "hermes-tools",
        instructions=(
            "Hermes Agent's tool surface, exposed for use inside a Codex "
            "session. Use these for capabilities Codex's built-in toolset "
            "doesn't cover: web search/extract, browser automation, "
            "subagent delegation, vision, image generation, persistent "
            "memory, skills, and cross-session search."
        ),

View on GitHub (pinned to c896c09c42)

Solutions

1. Install the mcp package into the same interpreter that runs hermes: pip install 'mcp>=1,<2' (respecting the repo's upper-bound pinning policy).
2. Verify with the exact interpreter: `python -c "from mcp.server.fastmcp import FastMCP"` — the chained {exc} in the message tells you if it is 'No module named mcp' versus a deeper import failure.
3. If a deeper failure, fix the conflicting/broken mcp install (pip install --force-reinstall mcp) rather than just adding it.

Example fix

# before
$ hermes mcp serve hermes-tools   # ImportError: requires the 'mcp' package

# after
$ pip install 'mcp>=1,<2'
$ python -c "from mcp.server.fastmcp import FastMCP; print('ok')"

def mcp_available() -> bool:
    try:
        from mcp.server.fastmcp import FastMCP  # noqa: F401
        return True
    except ImportError:
        return False

if not mcp_available():
    raise SystemExit("install the optional dependency: pip install 'mcp>=1,<2'")

try:
    _build_server()
except ImportError as exc:
    raise SystemExit(f"hermes-tools MCP server unavailable: {exc}") from exc

When it happens

Trigger: Running the hermes-tools MCP server (the entry point that calls _build_server) in an environment where 'mcp' is not installed, installed under a different interpreter/venv, or corrupted so that `from mcp.server.fastmcp import FastMCP` itself raises ImportError (the original exception is chained and included in the message).

Common situations: Using the repo's venv vs the system python mix-up; mcp listed as an optional extra that was never installed; a dependency conflict uninstalling/downgrading mcp; CI image missing the optional dependency.

Related errors

• The 'anthropic' package is required for the Anthropic provid
• OAuth popup was blocked — allow popups for this dashboard an
• OAuth failed to start
• OAuth server did not provide an authorization URL
• OAuth authorization failed

AI-assisted analysis of NousResearch/hermes-agent@c896c09c42 (2026-08-14). Data as JSON: /api/errors/fde510daf3dc5e71. Report an issue: GitHub.