jupyter-ai-hermes

Hermes Agent as an ACP persona for Jupyter AI, with live notebook context injection and custom MCP tools for cell metadata management.

What it does

• Injects live notebook context into every Hermes prompt — active notebook path, current cell ID, and cell content — so Hermes always knows what you're working on.
• Documents all available MCP CLI tools so Hermes prefers them over raw nbformat scripts.
• Registers custom MCP tools (set_cell_metadata, get_cell_metadata, list_cell_tags) for operations the built-in toolkit doesn't cover.

Requirements

• Python >= 3.12
• Jupyter AI with ACP client support
• Hermes Agent installed (the hermes binary must be on PATH)

Installation

pip install jupyter-ai-hermes

Then restart JupyterLab. The "Hermes" persona will appear in the Jupyter AI chat panel.

Configuration

By default the package searches for hermes in PATH. Override with:

export HERMES_BIN_PATH=/path/to/hermes

The MCP server URL defaults to http://localhost:3001/mcp. Override with:

export JUPYTER_MCP_URL=http://localhost:3002/mcp

Related Packages

• jupyter-hermes-proxy — Launch the Hermes Agent dashboard from the JupyterLab launcher panel with automatic port management via jupyter-server-proxy.

Both packages share the same HERMES_BIN_PATH environment variable convention.

MCP Tools

The package registers 3 custom MCP tools alongside the 18 built-in Jupyter AI notebook tools:

All tools are also available via the jupyter-mcp-cli command-line bridge:

# Set a cell as a Rise slideshow slide
jupyter-mcp-cli set_cell_metadata \
  --arg file_path=notebook.ipynb \
  --arg cell_id=cell-abc123 \
  --arg 'metadata={"slideshow":{"slide_type":"slide"}}'

# List all cells tagged with "important"
jupyter-mcp-cli list_cell_tags \
  --arg file_path=notebook.ipynb \
  --arg tags='["important"]'

Entry Points

Architecture

┌──────────────────────────────────────────────┐
│  JupyterLab                                  │
│  ┌─────────────┐    ┌─────────────────────┐  │
│  │ Notebook UI │    │ Jupyter AI Chat     │  │
│  │ (YDoc)      │◄──►│ ┌─────────────────┐ │  │
│  └─────────────┘    │ │ Hermes Persona  │ │  │
│                     │ │  ├─ gather_ctx  │ │  │
│  ┌─────────────┐    │ │  ├─ MCP docs    │ │  │
│  │ MCP Server  │◄──►│ │  └─ forward ──► │ │  │
│  │ :3001       │    │ └─────────────────┘ │  │
│  └─────────────┘    └─────────────────────┘  │
│                                              │
│  ┌─────────────────────┐                     │
│  │ jupyter-mcp-cli     │                     │
│  │ (CLI bridge)        │                     │
│  └─────────────────────┘                     │
└──────────────────────────────────────────────┘
         │
         ▼
┌──────────────────────┐
│  Hermes Agent (ACP)  │
│  ┌────────────────┐  │
│  │ Tool execution │  │
│  │ jupyter-mcp-cli│  │
│  └────────────────┘  │
└──────────────────────┘

Development

git clone git@github.com:dive4dec/jupyter-ai-hermes.git
cd jupyter-ai-hermes
pip install -e ".[dev]"
pytest

License

MIT