kb-mcp
You can manage and search a personal knowledge base of notes and bookmarks through MCP tools.
Search notes/bookmarks by full-text query, with optional tag filter and result limit.
Retrieve a full note by ID.
List notes, most recently updated first, with pagination and optional tag filtering.
List all tags with note counts.
Add new notes with title, body, and tags.
Save bookmarks with URL, title, notes, and tags.
Update a note's title, body, or tags.
Permanently delete a note or bookmark (destructive; user confirmation advised).
Imports bookmarks from a Firefox HTML bookmarks export, using link text as titles and bookmark folder names as tags; normalizes URLs and avoids duplicates on re-import.
Imports an Obsidian vault folder as notes, honoring front-matter titles and tags plus inline hashtags; supports idempotent re-syncs and optional pruning of files deleted from the vault.
Imports bookmarks from a Safari HTML bookmarks export, using link text as titles and bookmark folder names as tags; normalizes URLs and avoids duplicates on re-import.
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., "@kb-mcp what have I saved about DuckDB?"
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.
kb-mcp — a personal knowledge-base MCP server
An MCP server that gives an AI assistant a long-term memory you control: save notes and bookmarks, import folders and web pages, find anything with hybrid search, and let the assistant remember what it learns about you across conversations. It is built from scratch on the official MCP Python SDK (v2), with SQLite storage, a local embedding model (no API key, nothing leaves your machine), and tests at the protocol level.
Status: all five phases complete: MCP fundamentals, semantic search, hybrid search + evaluation, ingestion pipeline, agent memory. See the roadmap.
What the assistant gets
Tools. Every tool declares annotations so clients can auto-approve reads and confirm destructive calls. Every tool returns typed, schema-checked output.
Tool | Does | Annotations |
|
| read-only |
| Notes closest in meaning to a given note | read-only |
| One note in full | read-only |
| Recent notes, paginated with | read-only |
| Tags with counts | read-only |
| Save a note | write |
| Save a link (http/https only) | write |
| Change only the fields given | write, idempotent |
| Permanent delete | destructive |
| Fetch a web page, keep its readable text, save it as a note; re-importing refreshes it | write, idempotent, open-world |
| Recent import runs with counts and errors | read-only |
| Keep a fact about the user. Similar existing memories are returned for review instead of being duplicated or overwritten | write |
| Memories ranked by relevance × importance × recency | read-only |
| Everything remembered | read-only |
| Possible duplicates and stale minor memories (changes nothing) | read-only |
| Delete a memory and its earlier versions | destructive |
Resources, which the user or client can attach as context:
kb://notes/{note_id}: a note rendered as Markdownkb://tags: every tag with its note countkb://stats: counts of notes, bookmarks and tagskb://imports: the last 20 import runskb://memories: everything remembered, grouped by kind
Prompts, as reusable workflows:
summarize_tag(tag): summarise everything under a topic, with citationsfind_related(note_id): have the model search for connected notes and explain the linksstart_with_memory(topic?): open a conversation by recalling relevant memories
Related MCP server: NoteKeeper MCP
How semantic search works
Chunk. Each note is split into overlapping ~180-word passages, each prefixed with the note's title. Short notes stay as one chunk. This keeps a long note's different topics from blurring into one vector.
Embed. Each chunk goes through BAAI/bge-small-en-v1.5, a 384-dimensional model of about 70 MB, run locally with ONNX Runtime via
fastembed. Vectors are L2-normalised.Store. Vectors live in SQLite next to the notes (
note_chunks), tagged with the model name and a hash of the note's content.Search. The query is embedded, scored against every chunk with one matrix multiplication (cosine similarity), and each note is ranked by its best chunk.
Engineering choices:
Brute-force search, on purpose. A personal knowledge base has thousands of chunks, not millions. Exact search over a NumPy matrix takes about a millisecond and is never wrong, so an approximate index (FAISS, HNSW) would add complexity for no gain at this scale. The store has a single place to swap one in.
Always consistent. Notes are re-embedded when saved or edited. A content hash and the model name detect anything stale, including notes saved before Phase 2 existed or after a model change, and fix it before searching.
Fails soft. If the model can't load (for example, offline on first run), saving still works, and search falls back to keyword mode with a
noticesaying so, rather than erroring.
How hybrid search works (Phase 3)
Keyword and semantic search fail in opposite places:
Embeddings blur codes and identifiers.
23505,B905andHEAD@{2}carry almost no meaning.Keyword search misses anything phrased differently.
Hybrid search runs both and merges them:
Two candidate lists. BM25 in any-term mode (any word may match, so it finds more candidates) and semantic search each return their top 30.
Reciprocal Rank Fusion. Each note scores
Σ 1/(60 + rank)across the two lists. RRF uses ranks, not raw scores, so BM25 and cosine similarity never need calibrating against each other. A note found by both lists rises highest.Optional re-ranking (
kb-mcp --rerank). A cross-encoder (ms-marco-MiniLM-L-6-v2, about 80 MB, local) reads the query and each of the top 20 candidates together and re-orders them. It is more accurate than comparing vectors and much slower, so it only touches the shortlist.
Every step fails soft:
No embedding model: keyword results, with a notice.
No re-ranker: fused results, with a notice.
Measuring it
kb-mcp eval loads a hand-labelled set (eval_data.json: 52 notes, 60 queries) into a throwaway store and scores every mode on recall@5, MRR, nDCG@5 and latency. The queries are deliberately mixed so no single method can look perfect:
Query type | n | Example | Hard for |
paraphrase | 31 | "my container keeps getting killed" → the exit-code-137 note | keyword |
exact | 7 | "XCom" | — |
identifier | 11 | "23505", "B905", "0 6 * * 1-5" | embeddings |
fine-grained | 11 | "why did old messages disappear from my topic" among four near-identical Kafka notes | both |
Results (MacBook Air, Apple Silicon; MRR = how often the right note comes first, 1.0 = always):
Query type | n | keyword | semantic | hybrid (default) | hybrid + re-rank |
paraphrase | 31 | 0.00 | 0.91 | 0.85 | 0.87 |
exact | 7 | 1.00 | 1.00 | 1.00 | 1.00 |
identifier | 11 | 1.00 | 1.00 | 1.00 | 1.00 |
fine-grained | 11 | 0.00 | 0.79 | 0.85 | 0.88 |
all (MRR) | 60 | 0.30 | 0.92 | 0.90 | 0.91 |
all (recall@5) | 60 | 0.30 | 0.97 | 0.97 | 0.97 |
all (nDCG@5) | 60 | 0.30 | 0.92 | 0.91 | 0.92 |
median latency | 0.1 ms | 2.5 ms | 2.7 ms | 79 ms |
What the evaluation changed
The first version of hybrid search was worse than semantic alone (MRR 0.88 vs 0.92, and 0.82 vs 0.91 on paraphrases). Its misses pointed to the cause: in a small corpus, function words like "my" and "how" are rare, so BM25 gave them high weight, and "my query ran out of RAM" matched notes that happened to contain "my". Dropping stopwords from the keyword half raised hybrid to recall@5 0.97 and MRR 0.90. A test now guards against the regression.
Down-weighting the keyword list (0.5×) changed nothing, so the problem was noisy keyword candidates, not the fusion weights.
Conclusions
Semantic and hybrid are statistically tied. The 0.02 MRR gap is about one query out of 60. Each wins where you'd expect: semantic on paraphrases, hybrid on near-duplicates.
Hybrid stays the default. It equals semantic on recall, is better at telling near-identical notes apart, and keeps an exact-match path for codes in a larger, messier notebook. In this set the embeddings happened to handle every identifier anyway.
Re-ranking is optional (
--rerank). It is the best mode on near-duplicates (recall@5 1.00, MRR 0.88) but about 30× slower and no better overall.Caveat: 60 hand-written queries is small, and the dataset was extended while this phase was being built. Treat these as directional, not definitive.
Ingestion pipeline (Phase 4)
Bring in what you already have, and keep it in sync:
kb-mcp ingest folder ~/Notes # Markdown / .txt (an Obsidian vault works as-is)
kb-mcp ingest folder ~/Notes --prune # ...and remove notes whose file was deleted
kb-mcp ingest bookmarks ~/Downloads/bookmarks.html # browser export: Chrome, Safari, Firefox, Edge
kb-mcp ingest url https://example.com/article --tag reading
kb-mcp runs # what each run added, updated, skipped or failedSource | Title | Tags | Identity (for re-runs) |
Folder | front matter | front matter | folder + relative path |
Bookmarks | link text | bookmark folder names (browser root folders skipped) | normalised URL |
Web page |
| given with | normalised final URL |
How the pipeline is built:
Idempotent. Each imported note is tracked by
(source type, source id)with a content hash. A re-run updates only what changed and skips the rest. Unchanged items cost nothing, not even re-embedding.No duplicates. URLs are normalised: lower-case host, no
#fragment, noutm_*/fbclidtracking parameters, no trailing slash. A bookmark for a page you already saved by hand is linked to your note instead of copied, and your note is left untouched.Safe deletes.
--pruneis opt-in and only removes notes that came from that folder. It never touches hand-written notes or other sources.Partial failure is normal. A bad file or a page that times out is counted and logged, and the run continues. Every run is recorded in
ingest_runsand exposed throughimport_historyandkb://imports.SSRF-safe fetching.
import_urlcan be called by the model, so a prompt-injected page could try to make the server fetchlocalhost, a router or a cloud metadata endpoint. The fetcher therefore:allows only http(s)
resolves the hostname and refuses non-public addresses, re-checking after every redirect
caps pages at 2 MB with a 15-second timeout
accepts only HTML or plain text
Folder and bookmark imports stay CLI-only, so the model can never read arbitrary files from your disk.
Readable text only. Scripts, styles, navigation, headers, footers and sidebars are dropped.
<article>/<main>is preferred when it holds real content.
Keeping a folder in sync automatically (macOS/Linux cron, every morning at 7:45):
crontab -e
45 7 * * * /ABSOLUTE/PATH/TO/.venv/bin/kb-mcp ingest folder ~/Notes --prune >> ~/.kb-mcp/ingest.log 2>&1Agent memory (Phase 5)
Notes are documents you choose to save. Memories are short facts the assistant picks up on its own while you talk ("prefers concise answers", "applying for data engineering roles", "decided on DuckDB over Postgres"), so the next conversation starts with that context.
Ranking. Recall combines three signals, following the recency × importance × relevance idea from Generative Agents (Park et al., 2023):
score = 0.6 × relevance + 0.25 × importance/5 + 0.15 × 0.5^(age_days / 30)relevance is the cosine similarity to the current topic. With no topic, everything counts as relevant, so "what do you know about me?" returns the most important and recent memories.
importance (1–5) is set by the assistant when it saves the memory.
recency halves every 30 days since the memory was last confirmed.
Memories are never silently rewritten, and embeddings never decide what counts as "the same". The first design merged any new memory with cosine ≥ 0.92 to an existing one. Measuring that threshold on the real model (kb-mcp eval --memory) showed the idea itself was wrong, not just the number:
Pair | Relation | Cosine |
"Applying for data engineering jobs" / "Is job hunting for data engineer roles" | same fact | 0.880 |
"Lives in Virginia" / "Lives in Maryland" | conflict | 0.827 |
"Prefers concise answers" / "Likes short, concise replies" | same fact | 0.819 |
"Uses DuckDB for analytics" / "Uses Postgres for analytics" | conflict | 0.815 |
"Prefers concise answers" / "Prefers detailed explanations" | conflict | 0.798 |
"Uses Python for most projects" / "Writes most of their code in Python" | same fact | 0.783 |
"Working on the NBA data platform" / "Working on the Olist delivery project" | unrelated | 0.634 |
"Has a dog named Max" / "Likes hiking on weekends" | unrelated | 0.435 |
Rewordings of one fact (0.78–0.88) and contradictory facts (0.80–0.83) overlap completely, so any merge threshold either duplicates memories or silently overwrites "Maryland" with "Virginia". The design was changed so that:
Only identical text (ignoring case and spacing, same kind) is merged automatically.
Anything similar (cosine ≥ 0.75) is not saved.
rememberreturnsneeds_reviewwith the similar memories, and the assistant, which understands the sentences, decides. If it's the same fact, it does nothing. If the fact changed, it callsremember(..., supersedes=<id>), which keeps the old version as history but hides it from recall. If it's a different fact, it callsremember(..., force=true).At 0.75, every same-fact and conflicting pair above is surfaced for review, and both unrelated pairs are saved directly.
review_memoriesuses the same threshold to list possible duplicates and stale minor memories. It deletes nothing itself.
Privacy and control:
Memories live in the same local SQLite file as the notes.
The server instructions tell the assistant not to store secrets, credentials or sensitive personal details unless asked.
forgetdeletes a memory together with its history.kb-mcp memorieslists everything, andkb-mcp memories --export memories.jsonexports it.
Design decisions
The storage layer knows nothing about MCP.
store.pyis plain Python + SQLite, andserver.pyis a thin protocol layer over it. Later phases (vector search, ingestion) plug in behind the same interface.Errors are part of the contract. An unknown id, a bad URL or an invalid tag raises
ToolError, so the model gets an actionable message ("No note with id 999. Use search_notes…"), not a stack trace. Missing resources return a properResourceNotFoundprotocol error.Search is injection-proof. User text is tokenised and quoted before it reaches FTS5, so stray quotes or
AND/OR/NEARcan never break or alter the query. This is tested.The full-text index stays consistent by construction. It is an external-content FTS5 table kept in sync by triggers, so updates and deletes can't leave stale search results.
Two transports:
stdio, for Claude Desktop and other local clients
Streamable HTTP (
--http), for remote or multi-client use
Install and run
python -m venv .venv && source .venv/bin/activate
pip install -e ".[dev]"
pytest # 90 tests: storage, search, ingestion, memory, protocol, real stdio round-trip
kb-mcp reindex # one-time: downloads the embedding model and embeds existing notes
kb-mcp eval # keyword vs semantic vs hybrid vs re-ranked, by query type
kb-mcp --rerank # serve with cross-encoder re-ranking on
kb-mcp --db ~/.kb-mcp/kb.db # stdio
kb-mcp --http --port 8765 # Streamable HTTP at http://127.0.0.1:8765/mcpUse it from Claude Desktop
Add this to ~/Library/Application Support/Claude/claude_desktop_config.json (macOS), using the absolute path to the kb-mcp script in your virtualenv:
{
"mcpServers": {
"knowledge-base": {
"command": "/ABSOLUTE/PATH/TO/.venv/bin/kb-mcp",
"args": ["--db", "/Users/YOU/.kb-mcp/kb.db"]
}
}
}Restart Claude Desktop, then try "save a note that DuckDB's union_by_name opens every file at once" and "what have I saved about DuckDB?"
Inspect it
npx @modelcontextprotocol/inspector .venv/bin/kb-mcpTests
File | What it proves |
| CRUD, tag normalisation, BM25 ranking (title > body), prefix search, index consistency after update and delete, FTS-syntax safety, persistence |
| Chunking, embedding on write, staleness after edits and model changes, legacy-database backfill, best-chunk ranking, tag filter, similarity, failure never losing a write, RRF fusion, identifier rescue, re-ranking, eval harness and dataset integrity |
| Folder parsing (front matter, headings, hashtags, hidden folders), idempotent re-runs, change detection with re-embedding, scoped prune, per-item failures, bookmark parsing, URL normalisation and dedup, readable-text extraction, SSRF guard |
| Validation, identical-text merging, needs-review for similar memories, force and supersede paths, supersede history, relevance/importance/recency ranking with a fake clock, filtering irrelevant memories, forgetting whole chains, review, no-model fallback, persistence, export, tools end to end |
| Through a real MCP client (in-process): tool schemas and annotations, structured output, error contract, input validation, pagination, resources, prompts, search modes, fallback notices |
| The server launched as a subprocess over stdio, the way Claude Desktop runs it |
Roadmap
Phase | Adds | Status |
1. MCP fundamentals | Tools, resources, prompts, annotations, structured output, stdio + HTTP | ✅ |
2. Semantic search | Local embeddings, chunking, vector search, | ✅ |
3. Hybrid search | BM25 + vectors with RRF, cross-encoder re-ranking, harder evaluation (identifier and near-duplicate queries) | ✅ |
4. Ingestion pipeline | Folders, bookmark exports, web pages; idempotent upserts, URL dedup, scoped prune, run log, SSRF-safe fetching | ✅ |
5. Agent memory | Memories the assistant writes itself: model-judged dedup and supersede, recency × importance × relevance recall, review, forget, export | ✅ |
Layout
src/kb_mcp/store.py SQLite storage: notes, FTS5 keyword index, embeddings (no MCP dependency)
src/kb_mcp/embeddings.py embedding + re-ranking models (local fastembed, offline test doubles) and chunking
src/kb_mcp/memory.py agent memory: remember / recall / supersede / review / forget
src/kb_mcp/ingest.py ingestion: folder, bookmarks and web sources, the idempotent pipeline, SSRF guard
src/kb_mcp/evaluate.py retrieval evaluation (recall@5, MRR, nDCG@5, latency) on eval_data.json
src/kb_mcp/server.py MCP tools, resources, prompts, CLI entry point
tests/ storage, protocol and stdio testsAvailable Tools
8 toolsadd_noteAdd noteC
Save a new note.
Inputs: title (required), body, tags. Returns: id, uri, url, body, +4 more
delete_noteDelete noteBDestructive
Permanently delete a note or bookmark. Confirm with the user first.
Inputs: note_id (required). Returns: id, title, deleted
get_noteGet noteARead-onlyIdempotent
Fetch one note or bookmark in full.
Inputs: note_id (required). Returns: id, uri, url, body, +4 more
list_notesList notesARead-onlyIdempotent
List notes, most recently updated first. Paginate with offset / next_offset.
Inputs: tag, limit, offset. Returns: notes, total, next_offset
list_tagsList tagsBRead-onlyIdempotent
All tags in use, with how many notes carry each.
Inputs: no named parameters. Returns: result
save_bookmarkSave bookmarkB
Save a link with a title and optional notes.
Inputs: url (required), title (required), tags, notes. Returns: id, uri, url, body, +4 more
search_notesSearch notesBRead-onlyIdempotent
Full-text search over notes and bookmarks, best matches first.
Inputs: query (required), tag, limit. Returns: hits, query
update_noteUpdate noteAIdempotent
Change a note's title, body or tags. Fields left out stay as they are.
Inputs: note_id (required), body, tags, title. Returns: id, uri, url, body, +4 more
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 8 tools
Most tools have clearly distinct purposes (list/search/get/add/update/delete), and the descriptions distinguish search_notes from list_notes well. The main ambiguity is the note/bookmark boundary: get_note and delete_note operate on 'note or bookmark', but creation splits into add_note vs save_bookmark, and it's unclear whether update_note applies to bookmarks.
Names follow a predictable verb_noun snake_case pattern (list_tags, search_notes, get_note, update_note, delete_note). The only deviation is the create pair using different verbs, add_note vs save_bookmark, which adds mild inconsistency to an otherwise uniform set.
Eight tools is well-scoped for a knowledge-base server: list/search/read, two create paths, update, delete, and tag listing. Each tool earns its place and no tool looks like filler.
Note lifecycle is fully covered (create, read, list, search, update, delete) and tags can be set via update_note and enumerated via list_tags. The gap is bookmarks: there is no way to update a bookmark's URL/title/tags, and update_note is described only for notes, leaving bookmark maintenance a dead end.
Related MCP Connectors
Personal context for every AI: search, read, and write back to your private Markdown library.
Personal wiki and memory layer for AI assistants. Persistent, structured memory across sessions.
Read-it-later for AI agents. Save links, bookmarks, notes, and videos as Markdown and search them.
Long-term memory for Claude, ChatGPT, Cursor: search, save and organize notes, links, docs, videos.
Related MCP Servers
- FlicenseAqualityDmaintenanceEnables AI assistants to manage a personal markdown-based knowledge base with natural language interactions. Supports creating, searching, updating, and organizing notes across categories like people, recipes, meetings, and procedures.111-
- FlicenseNot gradedqualityDmaintenanceProvides AI assistants with tools to create, list, search, tag, and delete notes stored in a local SQLite database.-
- FlicenseNot gradedqualityCmaintenanceEnables AI assistants to capture bookmarks, sticky notes, todos, notes, and web archives, and to search and organize personal knowledge and memory across cloud-synced clients.-
- AlicenseNot gradedqualityCmaintenanceEnables AI assistants to search, read, and navigate a folder of Markdown notes as a knowledge base, with full-text search, backlinks, tags, metadata, and note resources for conversation attachment.1MIT