mattbeen/pageindex-mcp repository overview

⁠PageIndex MCP

Local FastMCP⁠ server that exposes PageIndex tree indexes over CLI catalog workspaces (./workspace/{catalog}/) to agents in Cursor, Claude Desktop, and other MCP clients.

Forked from VectifyAI/PageIndex⁠. Git Repo: https://github.com/mattbeen/pageindex-mcp⁠

⁠What it is

PageIndex builds a hierarchical “table of contents” tree from long documents (PDF via Docling → Markdown, or Markdown directly). This MCP lets agents:

1. List catalogs and documents under the workspace root
2. Inspect tree structure and pull page/line content
3. Insert, download, and delete indexed documents

MCP catalogs are the same filesystem layout as run_pageindex.py --catalog …. They are not PageIndexClient UUID / _meta.json workspaces.

⁠Tools

PDF inserts use the same pipeline as CLI --docling: Docling → Markdown → md_to_tree. Docling must be installed for PDF uploads.

⁠MCP config

Remote (HTTP):

"pageindex": {
  "type": "remote",
  "url": "http://127.0.0.1:8765/mcp/page-index/v1",
  "enabled": true,
  "timeout": 300000
}

Replace 127.0.0.1 with your machine IP when the server is bound with PAGEINDEX_MCP_HTTP_HOST=0.0.0.0.

Stdio:

{
  "mcpServers": {
    "pageindex": {
      "command": "python",
      "args": ["-m", "pageindex.mcp"],
      "cwd": "/path/to/PageIndex",
      "env": {
        "PAGEINDEX_WORKSPACE_ROOT": "/path/to/PageIndex/workspace",
        "OPENAI_API_KEY": "your_key_here"
      }
    }
  }
}

⁠Docker

Published image: mattbeen/pageindex-mcp⁠ (includes Docling for PDF insert).

⁠Pull from Docker Hub

docker pull mattbeen/pageindex-mcp:0.1.0

⁠Run the image

Create host folders and a config file, then start HTTP MCP on port 8765:

mkdir -p workspace uploads
# optional: copy config.example.yaml → pageindex/config.yaml (or any path you mount)

docker run -d --name pageindex-mcp \
  -p 8765:8765 \
  -e OPENAI_API_KEY=your_key_here \
  -e OPENAI_BASE_URL=http://your-litellm-host:8080/v1 \
  -e PAGEINDEX_WORKSPACE_ROOT=/data/workspace \
  -e PAGEINDEX_CONFIG_PATH=/config/config.yaml \
  -e PAGEINDEX_MCP_HTTP_HOST=0.0.0.0 \
  -e PAGEINDEX_MCP_HTTP_PORT=8765 \
  -e PAGEINDEX_MCP_HTTP_PATH=/mcp/page-index/v1 \
  -v "$(pwd)/workspace:/data/workspace" \
  -v "$(pwd)/pageindex/config.yaml:/config/config.yaml:ro" \
  -v "$(pwd)/uploads:/data/uploads" \
  mattbeen/pageindex-mcp:0.1.0

• MCP URL: http://localhost:8765/mcp/page-index/v1
• Mounts: workspace → catalogs; config.yaml → model/summary settings; uploads → use file_path like /data/uploads/doc.pdf
• Image listens on 0.0.0.0:8765 inside the container

⁠Docker Compose (build locally)

From this repo:

cp .env.example .env
mkdir -p workspace uploads
docker compose up --build -d

To use the Hub image instead of building, set image: mattbeen/pageindex-mcp:0.1.0 in docker-compose.yml (or pull first and retag). Same mounts and MCP URL as above.

⁠Workspace model

./workspace/
  {catalog}/
    {stem}.md                 # Docling or uploaded Markdown
    {stem}.pdf                # optional original PDF
    {stem}_structure.json     # tree index

• Catalog — single path segment under the workspace root (no /, \, ., ..).
• doc_id — document stem (filename without _structure / _structure_flash).
• insert_page_index — always persists the source into the catalog; requires a named catalog (no flat-root indexing in v1).

See [CONTEXT.md](CONTEXT.md) for invariants and ownership boundaries.

⁠Optional CLI

Same catalog layout without MCP:

python run_pageindex.py --pdf_path /path/to/doc.pdf --docling --catalog finance
python run_pageindex.py --md_path /path/to/doc.md --catalog finance

Flash (heuristic PDF structure, optional extra): python run_pageindex.py --flash --pdf_path …. Details: [CONTEXT.md](CONTEXT.md), [pageindex/flash/README.md](pageindex/flash/README.md).

⁠Attribution

Based on VectifyAI/PageIndex⁠. Licensed under the MIT License — see LICENSE⁠.