Oncrawl MCP Pi Extension

A Pi Agent extension that bridges the Oncrawl MCP Server directly into Pi – no Claude Code / Desktop required.

Installation

Via Pi (recommended)

pi install npm:oncrawl-mcp-pi-extension

Then set the required environment variables in your shell profile (~/.zshrc, ~/.bashrc, etc.):

export ONCRAWL_PYTHON_BIN="/Users/yourname/oncrawl-mcp-server/.venv/bin/python"
export ONCRAWL_API_TOKEN="your-token-here"
export ONCRAWL_WORKSPACE_ID="your-workspace-id"   # optional

Restart your shell (or source ~/.zshrc), then start Pi. That's it.

Manual installation

See the manual setup section below.

What it does

Pi Agent has no native MCP client. This extension fills that gap:

Spawns the Oncrawl Python MCP server as a subprocess on session start
Implements the MCP stdio protocol (newline-delimited JSON-RPC 2.0) in TypeScript
Auto-discovers all tools exposed by the server and registers them as native Pi tools
Cleans up the subprocess on session shutdown

All 21 Oncrawl tools become available directly in Pi, including:

| Tool | Purpose | |------|---------| | oncrawl_list_projects | List all projects in a workspace | | oncrawl_get_project | Project details + all crawl IDs | | oncrawl_get_schema | Discover queryable fields (call first!) | | oncrawl_search_pages | OQL-filtered page search | | oncrawl_aggregate | Group/count by any dimension | | oncrawl_site_health | Site health overview | | oncrawl_top_issues | Top SEO issues | | oncrawl_search_coc | Crawl-over-crawl diff | | oncrawl_export_pages | Full export, no 10k limit | | … | + 12 more |

Requirements

Pi Agent installed
Python 3.11+ with the oncrawl-mcp-server installed in a venv
An Oncrawl account with API access (project:read scope is sufficient)

Setup

1. Install the Oncrawl MCP Server

git clone https://github.com/Amaculus/oncrawl-mcp-server.git ~/oncrawl-mcp-server
cd ~/oncrawl-mcp-server
python3.13 -m venv .venv
source .venv/bin/activate
pip install -e .

2. Configure credentials

cp config.example.ts config.ts

Edit config.ts:

export const PYTHON_BIN = "/Users/yourname/oncrawl-mcp-server/.venv/bin/python";
export const MODULE = "oncrawl_mcp_server.server";
export const ONCRAWL_API_TOKEN = "your-token-here";
export const ONCRAWL_WORKSPACE_ID = "your-workspace-id-here";

Find your Workspace ID in the Oncrawl URL: https://app.oncrawl.com/workspace/<ID>/projects

Get your API token at Oncrawl → Settings → API

3. Install the extension into Pi

mkdir -p ~/.pi/agent/extensions/oncrawl-mcp
cp index.ts config.ts ~/.pi/agent/extensions/oncrawl-mcp/

4. Start Pi

The extension loads automatically on every session start. You'll see a status indicator in the footer:

🔄 Oncrawl MCP starting…
✅ Oncrawl ready – 21 tools

Usage examples

"List my Oncrawl projects"

"Get the schema for crawl 69c9a0e4a42fd1f846e095cd"

"Find all pages with status 404 that still have internal links pointing to them"

"Show me pages with depth > 5 and fewer than 3 inlinks"

"What's the status code distribution for this crawl?"

"Find orphan pages that are getting clicks from Google"

"Show me what changed between the last two crawls"

How it works

The MCP stdio protocol used by this server is newline-delimited JSON-RPC 2.0 (not the Content-Length framing described in some MCP specs). Each message is a single JSON object terminated by \n.

The handshake sequence:

Send initialize → receive server capabilities
Send notifications/initialized (no response)
Send tools/list → receive all tool definitions
For each tool call: send tools/call → receive result

TypeBox schemas are built dynamically from each tool's inputSchema, so new tools added upstream are picked up automatically without any changes to this extension.

File structure

oncrawl-mcp-pi-extension/
├── index.ts          # Extension entry point (Pi loads this)
├── config.ts         # Your credentials (git-ignored)
├── config.example.ts # Template – commit this, not config.ts
└── README.md

Credits

Oncrawl MCP Server by Antonio (Amaculus)
Pi Agent by Mario Zechner

MCP Servers