hebbianvault-mcp (Python)

Python sibling of @hebbianvault/mcp. Connect a Python MCP host to your Hebbian workspace with the same 13 tools and the same configuration. A thin client; all intelligence and access control live in the Hebbian service.

Quick start

pip install hebbianvault-mcp
# or with uv (preferred)
uv add hebbianvault-mcp

Generate a token from your Hebbian integrations page (AI Tools tab → Generate token).

Host configuration

Use the configuration for your host below. Replace your_token_here with the token you generated.

Claude Code

claude mcp add hebbian -e HEBBIAN_API_TOKEN=your_token_here -- npx -y @hebbianvault/mcp

Codex (CLI + Desktop app)

codex mcp add hebbian --env HEBBIAN_API_TOKEN=your_token_here -- npx -y @hebbianvault/mcp

For the Codex desktop app, add this to ~/.codex/config.toml, or use Settings → MCP servers:

[mcp_servers.hebbian]
command = "npx"
args = ["-y", "@hebbianvault/mcp"]
env = { HEBBIAN_API_TOKEN = "your_token_here" }

Gemini CLI

gemini mcp add hebbian -e HEBBIAN_API_TOKEN=your_token_here npx -y @hebbianvault/mcp

Claude Desktop

Add to ~/Library/Application Support/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "hebbian": {
      "command": "npx",
      "args": ["-y", "@hebbianvault/mcp"],
      "env": { "HEBBIAN_API_TOKEN": "your_token_here" }
    }
  }
}

Cowork

{
  "mcpServers": {
    "hebbian": {
      "command": "npx",
      "args": ["-y", "@hebbianvault/mcp"],
      "env": { "HEBBIAN_API_TOKEN": "your_token_here" }
    }
  }
}

Cursor

Add to .cursor/mcp.json:

{
  "mcpServers": {
    "hebbian": {
      "command": "npx",
      "args": ["-y", "@hebbianvault/mcp"],
      "env": { "HEBBIAN_API_TOKEN": "your_token_here" }
    }
  }
}

Generic Agent

For an MCP-compatible agent that accepts a standard input/output command:

HEBBIAN_API_TOKEN=your_token_here npx -y @hebbianvault/mcp

Or use the Python package:

# pip install hebbianvault-mcp   (or: uv add hebbianvault-mcp)
HEBBIAN_API_TOKEN=your_token_here hebbian-mcp

Configuration

Set HEBBIAN_API_TOKEN (or HEBBIAN_TOKEN) env var:

HEBBIAN_API_TOKEN=your_token_here hebbian-mcp

Or write ~/.config/hebbian/mcp-tenant.json:

{
  "token": "your_token_here"
}

Python server API

import os
os.environ["HEBBIAN_API_TOKEN"] = "your_token_here"
from hebbianvault_mcp import create_server
server = create_server()
# server.run() to start serving over stdio

Token scope

Your token decides what the adapter can see and do — a personal-workspace token gives access to your own knowledge; a company-workspace token gives access to the shared company workspace (where your role allows). Scope is decided by the Hebbian service. Search uses server-side full-text retrieval for every token scope, and the service decides which workspace a token searches. Traverse and provenance route company-scoped tokens to the company graph and other tokens to the workspace graph. If the advisory scope probe fails, the adapter caches the employee fallback for its process lifetime; restarting the MCP process clears that cached fallback.

Tools

Results only ever include what your token is allowed to see.

Development

uv venv && uv pip install -e ".[dev]"
pytest
ruff check src/ tests/

Node.js version

The canonical package is @hebbianvault/mcp on npm. This Python sibling has identical tools and configuration. Use whichever matches your MCP host environment.

License

Apache-2.0. See the root LICENSE file.