rabbithole
This server lets you create, resume, and explore branching document canvases called Rabbitholes, with support for answering questions and attaching local files.
Open a Rabbithole (
open_rabbithole): start a new hole from markdown content, a.mdfile, or a PDF ingest; resume a saved hole byhole_id; attach local images as assets; provide abase_urlfor resolving relative links/images.Ingest PDFs (
ingest_pdf): extract a local PDF into page-render PNGs and embedded images, optionally with per-page text, then stage or attach those assets to a hole.Answer branch questions (
answer_branch): respond to human-selected text or whole-document follow-ups, stream markdown chunks, use math/code/show visuals, include local image assets, and honor lenses like explain/eli5/example/deeper.List saved holes (
list_rabbitholes): find previously saved Rabbitholes by title, update time, and node count so you can resume them.Handle long-lived sessions: block while the human reads the canvas, receive
branch_requestevents, keep listening onkeep_listening, and recover from tool timeouts without losing asks.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@rabbithole open this document"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
Rabbithole
An infinite canvas for learning. Open a document, ask at any point, and follow each answer into a new document.

Open the web app · Explore the offline architecture tour
Rabbithole has two hosts and one canvas:
The static web app uses your chosen model endpoint or the coding-agent subscription already signed in on your machine.
The MCP server lets Claude Code, Codex, and other MCP clients answer while the canvas, storage, and local transport stay on your machine.
No account, telemetry, or hosted document store. Web documents live in your browser. MCP documents live under ~/.rabbithole/ unless RABBITHOLE_DIR overrides it.
Web
Visit rabbithole.ing, then paste a question or URL, drop Markdown or PDF, or import a Rabbithole file.
The web app supports OpenRouter, local and custom OpenAI-compatible endpoints, and the optional subscription bridge:
npx @shlokkhemani/rabbithole bridgeThe bridge prints a private pairing link and connects the page to an installed, signed-in Claude Code or Codex CLI. It binds only to loopback.
Related MCP server: pdf-context
MCP quick start
Requires Node 18+ and a browser.
Claude Code:
claude mcp add rabbithole -- npx -y github:shlokkhemani/rabbitholeCodex:
codex mcp add rabbithole -- npx -y github:shlokkhemani/rabbitholeThen start a fresh agent session and say:
Open this document in Rabbithole.
The tool call stays pending while the agent listens for canvas asks. If a client enforces a short MCP tool timeout, raise that client's timeout; saved asks survive disconnects and resume.
Develop
git clone https://github.com/shlokkhemani/rabbithole.git
cd rabbithole
npm install
npm run build
npm testUseful references:
The canvas and frozen snapshots remain self-contained HTML. Package tarballs include the browser bundles built during packaging, so registry installs need no consumer-side build.
License
MIT. See LICENSE.
Available Tools
4 toolsanswer_branchA
Answer one pending branch request from an open Rabbithole. Called after open_rabbithole or answer_branch returns status='branch_request'. Write a focused, well-formatted markdown answer to the human's question about their selection - use selected_text, parent_node_title, and lineage for context (you already hold the documents you authored). If selected_text is empty, answer conversationally about the parent document as a whole. If the request has a 'lens', match that style.
Authoring vocabulary:
Base notation: GFM markdown, $...$/$$...$$ and (...)/[...] math, and highlighted language-tagged code fences.
If the answer is content fetched from a URL or repo, pass its document URL as base_url so relative images and links resolve.
If the answer uses a local image, pass assets: [{ name, file_path }] and reference it as
; use this for screenshots, generated diagrams, and other non-web images.Use ```show when a concept is spatial or structural: architecture, memory layout, relationships.
show dialect: HTML/CSS/inline-SVG only; no scripts. Scripts and unsafe attributes are stripped.
show craft: prefer HTML/CSS layout with flexbox/grid over absolute SVG coordinates.
Design visuals for about 380px card width; make them fluid and keep labels short.
Use theme tokens, never hardcoded colors, so visuals match light and dark themes: --fg, --fg-bold, --fg-dim, --fg-faint, --node-bg, --bar-bg, --border, --border-focus, --accent, --accent-contrast, --code-bg, --hl, --hl-strong, --warn, --font-ui, --font-doc, --font-mono.
Example show:
<style>.flow{display:grid;gap:8px}.box{border:1px solid var(--border);padding:8px;border-radius:6px}</style>
<div class='flow'><div class='box'>Parse</div><div class='box' style='background:var(--hl)'>Render</div></div>Streaming choreography: send prose in 1-3 sentence chunks as usual.
Emit each visual fence contiguously, ideally in one chunk; readers see a placeholder until the fence closes.
Interleave prose -> visual -> prose when useful. Use a visual only when it genuinely carries the explanation.
Finish streaming by sending the remaining final chunk in a normal call with a short 'title'. Partial chunks concatenate verbatim: include your own spacing/newlines and never repeat text already sent. The final call blocks and returns the next event. If it returns status='keep_listening', immediately call open_rabbithole { hole_id }; if the host reports a tool timeout (e.g. timed out awaiting tools/call), do the same. Do not re-send content; asks are saved.
Inputs: content (required), request_id (required), session_id (required), title, +3 more.
ingest_pdfA
Extract a local PDF into Rabbithole image assets and per-page text. Produces 2x page render PNGs named page-001.png, page-002.png, etc. plus opportunistic embedded rasters named embed-p001-01.png when the PDF contains extractable images. The agent should compose markdown itself, using page renders as the dependable figure source and embedded rasters when they are cleaner, then call open_rabbithole with the returned ingest_id (or pass hole_id here to attach assets directly to an existing hole). For arXiv links, prefer fetching the HTML version and opening that markdown with base_url instead of ingesting the PDF.
Inputs: file_path (required), pages, hole_id, include_text.
list_rabbitholesA
List saved Rabbitholes (most recently updated first) so you can resume one by hole_id via open_rabbithole. Returns id, title, last-updated time, and node count for each.
Inputs: no named parameters.
open_rabbitholeA
Open a document on an infinite canvas so the human can read it and dive down rabbit holes. Start a NEW hole with { title, content } (or { title, file_path }), or RESUME a saved one with { hole_id } (use list_rabbitholes to find it). When opening content fetched from a URL or repo, pass the document's own URL as base_url so relative images and links resolve. For local images that are not on the web, pass assets and reference them as
. For a PDF already processed with ingest_pdf, pass ingest_id when starting the new hole and reference the returned asset names as
. The canvas opens in the browser and this call BLOCKS until the human acts. It returns status='branch_request' when the human selects text and asks a question — answer it with answer_branch. A branch_request with EMPTY selected_text is a follow-up question about the parent document as a whole (a chat reply beneath it) — answer conversationally in that document's context. A branch_request may carry a 'lens' (explain | eli5 | example | deeper) — the question text spells out the style the human tapped; honor it. One marked saved=true was asked while no agent was listening — answer it like any other. On a resumed hole the first branch_request carries a 'rehydration' field with the whole tree (and any saved_asks); read it to reload your context. Long waits periodically return status='keep_listening' with hole_id; immediately call open_rabbithole { hole_id } to keep listening, and do not re-send content. If the host reports a tool timeout (e.g. timed out awaiting tools/call), also re-call open_rabbithole { hole_id }; nothing is lost and asks are saved. It returns status='session_closed' when the human clicks Done or closes the tab.
Inputs: title, assets, content, hole_id, +3 more.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 4 tools
Each tool has a clear, distinct purpose: opening/resuming rabbitholes, answering branch requests, ingesting PDFs, and listing saved ones. No overlap in functionality.
All tool names follow the `verb_noun` pattern (e.g., list_rabbitholes, open_rabbithole, answer_branch, ingest_pdf), providing a consistent and predictable interface.
With 4 tools, the set is tightly scoped to the rabbithole interaction domain—opening, answering, ingesting, and listing. No tool feels redundant, and the number is appropriate for the focused purpose.
The tools cover core workflows well, but missing explicit update/delete functionality for rabbitholes. However, the blocking nature of open_rabbithole and the branch-answer loop cover most user interactions adequately.
Maintenance
Related MCP Connectors
Self-hosted AI workspace: semantic RAG document search, long-term memory, and AI chat via MCP.
Markdown-based note-taking with a hosted MCP server. Your notes serve you and your AI.
Query your own PDFs and documents from any MCP client. Every answer cites the page it came from.
Driflyte MCP server which lets AI assistants query topic-specific knowledge from web and GitHub.
Related MCP Servers
- FlicenseNot gradedqualityDmaintenanceA local RAG server using the Model Context Protocol (MCP) to allow AI assistants to query private documents with persistent memory and support for many file formats.1-
- AlicenseAqualityDmaintenanceA local-first MCP server that ingests PDFs, extracts structure, and provides semantic search and sequential navigation tools for AI clients to query and learn from documents.10MIT
- AlicenseNot gradedqualityBmaintenanceMCP server for local RAG over personal notes, PDFs, and documents, enabling plain-English querying and hybrid search with multi-hop context expansion.MIT
- AlicenseNot gradedqualityDmaintenanceMCP server for a self-hosted RAG system that enables AI tools to search and retrieve grounded answers from locally ingested documents via MCP tools, with local embeddings and no API key required.MIT