personal-knowledge-mcp
This server does not currently have a deployable release on Glama. Follow the repository's setup instructions to install and configure it for your MCP client, including any required credentials and local dependencies.
personal-knowledge-mcp
A local-first Model Context Protocol server that gives Claude searchable, cited access to your own notes. Point it at a folder of Markdown files and ask Claude things like "what did I write about running postmortems?" It answers from your notes and tells you which note and section each claim came from.
flowchart LR
N[("Notes folder<br/>Markdown, text")] --> C[Heading-aware<br/>chunker]
C --> K[BM25<br/>keyword index]
C --> E["Embeddings<br/>(local model)"]
Q([Question]) --> K
Q --> E
K --> F[Reciprocal<br/>rank fusion]
E --> F
F --> P[Top passages<br/>with note + section]
P --> M{{"MCP tools<br/>search_notes · read_note<br/>list_notes · ask_notes"}}
M --> A([Claude Desktop,<br/>Claude Code, any MCP client])What it does
Hybrid retrieval. Every query runs against a BM25 keyword index and a sentence-embedding index, and the two rankings are fused with reciprocal rank fusion. Keywords catch exact terms (an acronym, a name); embeddings catch paraphrases.
Local-first. Embeddings are computed on your machine with a small open model (all-MiniLM-L6-v2, run with ONNX Runtime). Indexing and searching send nothing to any service.
Cited answers. The optional
ask_notestool sends only the retrieved passages to Claude with citations enabled, so each answer comes back with the exact quoted span and the note it came from. If the notes do not contain the answer, it says so.Measured. A golden set of 50 questions scores retrieval at the section level (recall@k, MRR) for keyword-only, embedding-only and hybrid ranking. It runs in CI on every push.
Related MCP server: pando
Retrieval results
Measured in CI (run 43665978908) with the real embedding model, on 50 questions:
Ranking | Recall@1 | Recall@3 | Recall@5 | MRR@10 |
Keyword only (BM25) | 50% | 66% | 70% | 0.578 |
Embeddings only | 64% | 80% | 90% | 0.738 |
Hybrid (RRF, default) | 56% | 80% | 84% | 0.688 |
Split by question type:
Question type | Ranking | Recall@1 | Recall@3 | MRR@10 |
Paraphrased (42): few words shared with the note | Keyword | 43% | 60% | 0.510 |
Embeddings | 60% | 79% | 0.706 | |
Hybrid | 50% | 76% | 0.640 | |
Keyword (8): shares the note's key terms | Keyword | 88% | 100% | 0.938 |
Embeddings | 88% | 88% | 0.906 | |
Hybrid | 88% | 100% | 0.938 |
What the eval showed
The expectation going in was that hybrid would beat both single rankings. It did not:
Embeddings carry paraphrased questions. Keyword search finds the right section first only 43% of the time when the question shares few words with the note; embeddings manage 60%.
Equal-weight fusion costs accuracy on those questions. A weak keyword ranking drags a good embedding ranking down (MRR 0.640 against 0.706).
Keywords still earn their place on exact terms. For questions built around a specific term (
DLQ alarm,strangler fig), hybrid matches keyword search at 100% recall@3 while embeddings alone drop to 88%.
To see whether weighting the embedding ranking more heavily would fix this, the eval sweeps that weight on half the questions (dev) and reports the other half (test). On dev, every weight from 0.5 to 6 lands within 0.02 MRR of the others (0.667 to 0.683), with equal weighting marginally best, so the data does not justify changing the default. The test half does favour heavier embedding weights (MRR 0.692 at weight 1, 0.777 at weight 4), which is a reason to grow the question set, not to tune on test.
Hybrid stays the default because personal notes are full of exact terms (names, acronyms, ticket numbers) that embeddings blur, and because its recall@3 equals the best single ranking overall. --mode vector and --mode bm25 are one flag away, and the weight is a parameter (vectorWeight).
Read these with their limits in mind: the corpus is the bundled
sample notes (14 notes, 69 passages) and 50 questions is a
small set, so differences of a few points are noise. A result only counts if it
is the exact section that answers the question, not just the right note. CI
fails if hybrid recall@3 drops below 75%. Reproduce with npm run eval.
Use it with Claude
Requires Node.js 20 or later.
git clone https://github.com/Ankita-0607/personal-knowledge-mcp.git
cd personal-knowledge-mcp
npm installClaude Desktop. Add this to claude_desktop_config.json (Settings →
Developer → Edit Config), with your own paths:
{
"mcpServers": {
"personal-knowledge": {
"command": "node",
"args": ["/absolute/path/to/personal-knowledge-mcp/bin/kb.mjs", "serve"],
"env": { "KB_NOTES_DIR": "/absolute/path/to/your/notes" }
}
}
}Claude Code.
claude mcp add personal-knowledge --env KB_NOTES_DIR=/absolute/path/to/your/notes -- node /absolute/path/to/personal-knowledge-mcp/bin/kb.mjs serveLeave KB_NOTES_DIR out to try it with the bundled sample notes. The first
search downloads the embedding model (about 90 MB) and builds the index; after
that only changed passages are re-embedded.
Tools the server exposes
Tool | What it does |
| Returns the most relevant passages for a question, each with its note path and section heading. |
| Returns one full note, for when a passage needs its surrounding context. |
| Lists every note with its title and last-modified date. |
| Re-scans the folder after you add or edit notes. |
| Answers from the notes with citations. Registered only when |
In a Claude client you rarely need ask_notes: Claude calls search_notes and
reasons over the passages itself. ask_notes is for clients that want a short,
sourced answer in one call, and for the command line.
Use it from the terminal
npm run kb -- search "how do we handle messages that keep failing?"
npm run kb -- search "DLQ alarm" --mode bm25
npm run kb -- --notes ~/notes index
export ANTHROPIC_API_KEY=...
npm run kb -- ask "What limits apply to autonomous coding agents?"search shows where each passage ranked in the keyword and the embedding
ranking, which makes it easy to see why a result came back.
How it is built
Piece | File | Notes |
Chunker | Splits on Markdown headings, not fixed sizes, and stores the heading trail ( | |
Keyword index | BM25 in about 60 lines. | |
Embeddings | Local sentence embeddings behind an | |
Fusion | Reciprocal rank fusion: no score calibration needed between BM25 and cosine similarity, which live on unrelated scales. Exact linear scan over vectors, which is the right choice at personal-notes scale. | |
Index | One JSON file. Chunks are content-hashed, so re-indexing after an edit only embeds what changed. | |
Answers | Passages go to Claude as documents with citations enabled; the response's citations are mapped back to note and section. | |
MCP server | Built on the official TypeScript SDK, stdio transport. |
Safety choices
read_noteis confined to note files inside the notes folder. Path traversal, absolute paths, symlinks that leave the folder, hidden files and non-note file types are refused, so an MCP client is not handed a general file-read primitive.Notes are treated as data. The answer prompt tells the model that instruction-like text inside a note is content to report on, not something to act on.
Nothing leaves your machine unless you use
ask/ask_notes, and then only the handful of retrieved passages do.
Tests and evals
npm test # 100+ tests, no model download, no API key
npm run eval # retrieval eval with the real embedding model
npm run eval:answers # cited-answer eval (needs ANTHROPIC_API_KEY)The tests drive the real server through an MCP client over an in-memory transport, so tool listing, argument validation and error handling are checked at the protocol level. One test verifies the golden set's answer key against the notes, so the eval cannot silently point at a section that was renamed.
The answer eval checks two things using the API's own citations rather than a second model as judge: that answerable questions cite the note that holds the answer, and that questions the notes cannot answer are declined.
No live answer-eval run has been recorded in this repository yet.
Limitations
Markdown and plain text only. PDFs and other formats would need an extraction step.
The embedding model is English-centric and small; it trades some accuracy for running anywhere with no GPU.
The linear vector scan is exact and fast for thousands of passages. Beyond that, swap in an approximate index behind the same
Retriever.The sample notes are written for this demo, and the figures in them are illustrative.
Development
This project was built with AI assistance (Claude Code). Issues and suggestions are welcome.
MIT licensed.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
This server cannot be deployed
Maintenance
Related MCP Connectors
Serve a folder of Markdown notes as an MCP server: hybrid search, reading, and sourced answers.
Notes and memory assistant: one Markdown vault that Claude, ChatGPT and any MCP client can share.
Search and reason over your Obsidian-style Markdown vault, right from ChatGPT.
Persistent memory layer for AI tools. Save and recall notes across Claude and other MCP clients.
Related MCP Servers
- AlicenseNot gradedqualityCmaintenanceEnables Claude Code to search and retrieve from a local knowledge base of markdown notes using hybrid semantic+keyword search, keeping data entirely offline.MIT
- AlicenseNot gradedqualityBmaintenanceEnables Claude to search, read, write, and manage a local markdown vault through 8 tools, turning your notes into an AI-accessible knowledge base.3 npmAGPL 3.0
- AlicenseAqualityCmaintenanceEnables semantic search and reading of Obsidian Markdown notes through read-only MCP tools, allowing Claude to retrieve relevant passages from a local vault.3MIT
- FlicenseNot gradedqualityAmaintenanceEnables users to create, link, search, explore, and synthesize atomic notes through Claude and other MCP-compatible clients, using Markdown files backed by a SQLite index.-