Muninn
Muninn is an MCP research knowledge-base server for searching a PDF corpus and returning citable evidence from it.
Run semantic search across raw paper text, Claude notes, and HyDE bridges, with optional document/type filters and page-level citations.
Use a HyDE hypothesis to recover missed searches and tag results as
retrieved_via=hyde.Save successful HyDE hypotheses as reusable indexed bridges.
List corpus documents with IDs, titles, and page counts.
Fetch the full text of any page for context.
Generate APA-7 citations, including in-text and reference-list forms.
Render PDF pages as images, optionally highlighting a quote or passage.
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., "@Muninn search for transformer attention mechanisms"
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.
Muninn — Page-Citable Research Knowledge Base + MCP Server
Named after Odin's raven of memory. From research PDFs → chunked at page level →
embedded (BAAI/bge-small-en-v1.5) → Qdrant vector DB → served over MCP so any
future Claude session (desktop, web, phone) can query the corpus with exact
filename, p. N citations — no re-reading, no chat-context cost.
Note:
pdfs/,notes/, andqdrant_db/are not included in this repo.pdfs/holds the source papers,notes/holds Claude's generated reading notes, andqdrant_db/is the resulting vector DB — all excluded for privacy, since they contain personal research material and its derived content rather than shareable code.
Layout
pdfs/ the source PDFs
notes/ Claude's reading notes (notes*.jsonl) — re-ingestable
ingest.py PDFs + notes → qdrant_db/ (run once, and after adding PDFs)
muninn_mcp.py MCP server (stdio locally, Streamable HTTP when hosted)
push_to_cloud.py local qdrant_db/ → Qdrant Cloud (one command)
Dockerfile Hugging Face Space deployment
qdrant_db/ the vector DB (created by ingest.py)Data model (collection muninn): type=raw — verbatim chunks, ~1000 chars,
never crossing page boundaries → every chunk has exactly one (source_file, page); type=page — full page text (backs get_page, and later
page-rendering/highlighting: exact search_for → sentence pieces → fuzzy
word alignment → semantic nearest-chunk fallback); type=claude_note —
interpretation layer. Raw = ground truth, notes = orientation.
Related MCP server: Research Citations MCP Server
Dependencies and verification
Use Python 3.11–3.13. Python 3.10 is no longer supported because the fixed Pillow 13 and filelock 4 release lines require Python 3.11. MCP stays on its maintained 1.x line, and PyMuPDF stays on 1.x to avoid an unrelated 2.x migration. The declared security floors cover certifi, filelock, HTTP/2, MCP and Pillow.
uv sync --frozen
uv run --frozen python -m unittest discover -s tests -p test_dependency_updates.py -vThe acceptance checks exercise real embeddings, an isolated Qdrant database,
retrieval/citations, PDF rendering/highlighting and MCP tool calls using synthetic
fixtures. They never open the research corpus. The first run downloads the public
embedding model; subsequent runs can reuse FASTEMBED_CACHE_PATH.
After an intentional dependency update, regenerate the Docker dependency export:
uv lock --upgrade
uv export --locked --no-dev --no-emit-project --format requirements-txt --no-header --output-file requirements.txtCommit pyproject.toml, uv.lock and requirements.txt together. Docker installs
the exact exported versions with required artifact hashes instead of resolving
unbounded dependencies during each build. .dockerignore excludes everything
except the build recipe, server, dependency export and explicitly shipped PDFs.
For a data-free build check, use a controlled context containing those code files
and an empty pdfs/ directory. Do not copy private PDFs into a shared image or
publish a corpus-containing image without reviewing its contents and permissions.
A build/synthetic test is not a deployment or verification of hosted credentials.
Step 1 — Ingest (your machine, ~2-3 min)
cd <this folder>
uv run ingest.py # downloads bge-small (~130MB) once, builds qdrant_db/Step 2 — Use locally right away (optional)
Claude Desktop → claude_desktop_config.json:
{"mcpServers": {"muninn": {"command": "uv",
"args": ["run", "--directory", "/ABSOLUTE/PATH/TO/THIS/FOLDER", "muninn_mcp.py"]}}}Claude Code: claude mcp add muninn -- uv run --directory /ABSOLUTE/PATH muninn_mcp.py
Note: Qdrant local mode is single-process — stop the MCP server before
re-running ingest.py.
Step 3 — Host it (laptop-off access, $0/mo)
3a. Qdrant Cloud (free tier, 4GB): create a cluster at cloud.qdrant.io, copy URL + API key, then:
QDRANT_URL=https://xxxx.cloud.qdrant.io QDRANT_API_KEY=... uv run push_to_cloud.py3b. HF Space: create a Space (SDK = Docker) and push Dockerfile,
.dockerignore, requirements.txt and muninn_mcp.py. The build also expects a
pdfs/ directory. Include only PDFs explicitly approved for that destination;
for a code-only build, retain a non-sensitive pdfs/.gitkeep placeholder so Git
preserves the directory. Provide approved PDFs separately if remote rendering is
needed. Keep the Space private unless its
contents and access controls have been reviewed. In Space Settings → Variables
and secrets set:
name | kind | value |
| secret |
|
| variable | your cluster URL |
| secret | your cluster key |
3c. Connect Claude: Settings → Connectors → Add custom connector →
https://<user>-<space>.hf.space/mcp-<TOKEN>
MCP tools
search(query, top_k, doc_id, note_type) → ranked chunks with citation;
list_documents() → corpus inventory; get_page(doc_id, page) → full page
text. Retrieval tip: if a query misses, try HyDE (in the corpus, doc
322d71209a2f): write a hypothetical paragraph answering the question and
search with that.
Adding papers later
Drop PDFs into pdfs/, re-run uv run ingest.py (idempotent per file), then
push_to_cloud.py if hosted. Ask Claude to read the new paper and append a
note to notes/ for the interpretation layer.
Available Tools
6 toolsget_citationA
APA-7 citation for a document: in-text (parenthetical + narrative) and the full reference-list entry. Use these verbatim when writing — the corpus is APA only, never mix styles. For a direct quote, add the page to the in-text form: '(Author, Year, p. N)'.
Args: doc_id: document id from search/list_documents.
Inputs: doc_id (required).
get_pageA
Full text of one page of a document — for reading context around a search hit.
Args: doc_id: document id from search/list_documents. page: 1-based page number.
Inputs: page (required), doc_id (required).
list_documentsA
List all documents in the knowledge base with doc_id, title, and pages.
Inputs: no named parameters. Returns: result
render_pageA
Render a PDF page as an image, optionally with a passage highlighted. Use after search/get_page to SHOW the user the exact source location.
Args: doc_id: document id from search/list_documents. page: 1-based page number. highlight: passage to highlight. Verbatim raw-chunk text from search() always works; paraphrases usually work too — matching falls back exact -> sentence pieces -> fuzzy word alignment -> semantic (embeds the text and highlights the nearest raw chunk on this page). Returns the image plus a highlight_method report. "" = no highlighting.
Inputs: page (required), doc_id (required), highlight.
save_hydeA
Persist a HyDE hypothetical document as a reusable type=hyde bridge.
Use after a search(query, hypothesis=...) fallback produced good grounding, so the same retrieval miss becomes an indexed hit next time (searchable via note_type="hyde" or "everything"). A hyde bridge is generated text, never a citable source. Idempotent per (doc_id, query) — re-saving updates in place.
Args: query: the user query this hypothesis answers (used for the bridge id). hypothesis: the hypothetical answer paragraph to store and embed. doc_id: optional document this bridge is about ("" = corpus-wide). title: optional label ("" = derived from the query).
Inputs: query (required), hypothesis (required), title, doc_id.
searchA
Semantic search over the corpus. Returns chunks with page-level citations.
Args: query: natural-language question or topic. top_k: number of results (default 6). doc_id: restrict to one document (from list_documents), "" = all. note_type: which payload types to search — "raw" (verbatim paper text, ground truth), "claude_note" (Claude's reading notes), "hyde" (generated HyDE bridges only), "all" (raw + claude_note, the default), or "everything" (raw + claude_note + hyde). hypothesis: HyDE fallback. When the plain query misses (low scores), pass a short hypothetical answer paragraph here. It is embedded and averaged with the query (Gao et al., 2023) to retrieve REAL corpus chunks via the hypothesis. Each hit is tagged retrieved_via="hyde". "" = ordinary query-vector search (retrieved_via="direct").
Inputs: query (required), top_k, doc_id, note_type, +1 more. Returns: result
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 6 tools
Every tool has a clearly distinct purpose: listing documents, getting page text, retrieving citations, rendering pages, saving hypothetical documents, and searching. No overlap or ambiguity.
Most tool names follow a verb_noun pattern (list_documents, get_page, get_citation, render_page, save_hyde). 'search' is a single verb but is a standard exception for search functionality. Overall consistent.
Six tools is well-scoped for a knowledge base server covering listing, reading, citation, rendering, saving, and searching. Each tool is essential and not excessive.
The tool set covers core read operations and search with HyDE support, plus citation and visualization. Missing write/update operations for raw documents, but intentional for a knowledge base. Minor gap for editing documents.
Maintenance
Related MCP Connectors
Query your own PDFs and documents from any MCP client. Every answer cites the page it came from.
Academic research MCP server for paper search, citation checks, graphs, and deep research.
MCP server for querying Forkast documentation
Peer-reviewed scientific paper & arXiv preprint search MCP with citations, abstracts & PDF links.
Related MCP Servers
- AlicenseAqualityCmaintenanceMCP server for searching and retrieving arXiv papers with full-text PDF extraction.52MIT
- AlicenseNot gradedqualityDmaintenanceAn MCP server for searching and citing research papers using RAG, enabling semantic search, citation finding, and question answering over a collection of PDF papers.ISC
- FlicenseAqualityCmaintenanceEnables semantic search across personal PDF paper collections with page-level citations, allowing users to query their library from any MCP-capable client.9-
- FlicenseNot gradedqualityDmaintenanceAn MCP server that exposes grounded, source-attributed question-answering over a collection of PDF documents.-