HippoBox

HippoBox is a unified FastAPI + FastAPIMcp for managing a personal knowledge base. It provides CRUD operations for knowledge entries, semantic search powered by embeddings, and MCP tool integration for use in Claude Desktop or other MCP-compatible clients.

Overview

See the knowledge entry once it is created in HippoBox.

Hippo Search (VDB)

Use Hippo Search to run VDB searches over your knowledge.

setup MCP

Configure MCP to connect HippoBox with Claude, Cursor, and Codex.

Running as a package

pip install hippobox

# Basic execution
hippobox run

# Custom host and port
hippobox run --host 0.0.0.0 --port 8080

Quick Start from Source

1. Install uv

macOS / Linux

curl -LsSf https://astral.sh/uv/install.sh | sh

Windows (PowerShell)

irm https://astral.sh/uv/install.ps1 | iex

2. Setup Project

cd src/backend
uv sync

3. Run Server

macOS / Linux

cd src/backend
uv run uvicorn hippobox.server:app --reload

4. Run Frontend

cd src/frontend
npm install
npm run dev # watch build to keep src/frontend/dist updated for backend serving
npm run dev:vite # Vite dev server with HMR (default 5173)
npm run build # build to src/frontend/dist for backend serving
npm run preview # preview the built bundle

MCP settings

Using with Claude Desktop

Add the following to your claude_desktop_config.json:

{
    "mcpServers": {
        "hippobox": {
            "command": "uvx",
            "args": [
                "mcp-proxy",
                "--transport",
                "streamablehttp",
                "http://localhost:8000/mcp"
            ],
            "env": {
                "API_ACCESS_TOKEN": "<YOUR_ACCESS_TOKEN>"
            }
        }
    }
}

Using with Cursor

Add the following to your Cursor mcp settings:

{
    "mcpServers": {
        "hippobox": {
            "url": "http://localhost:8000/mcp",
            "headers": {
                "Authorization": "Bearer <YOUR_ACCESS_TOKEN>"
            }
        }
    }
}

Using with Codex

Add the following to your config.toml:

[mcp_servers.hippobox]
startup_timeout_sec = 30
command = "uvx"
args = [
    "mcp-proxy",
    "--transport",
    "streamablehttp",
    "http://localhost:8000/mcp"
]
[mcp_servers.hippobox.env]
API_ACCESS_TOKEN = "<YOUR_ACCESS_TOKEN>"