lance-kb
An MCP knowledge-base server for searching, managing, ingesting, and versioning notes and document chunks.
Search notes/chunks with hybrid, vector, or text modes; filter by project, kind, tag, and version; set result count with
k.Fetch a single note or chunk by id with full text and metadata.
Add notes with title, text, project, and tags; returns the new id.
Update a note’s title, text, project, or tags; it is re-embedded automatically.
Delete a note or chunk; it remains recoverable through version history.
Ingest a folder of Markdown/text/reStructuredText files, chunked with file/line provenance; unchanged files are skipped.
List knowledge-base versions and restore an older version, writing a new version so history is kept.
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., "@lance-kb Save a note: cache entries expire after 15 minutes, tagged cache"
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.
lancedb-kb-mcp
A knowledge base for Claude (or any MCP client) that lives in one folder on disk.
Hybrid search: vector similarity and BM25 keyword search in one query, merged with reciprocal rank fusion. Meaning-based questions and exact strings like
E1042both work.Notes: Claude can save, update and delete notes while it works.
Folder ingest: Markdown, text, reStructuredText and PDF files are chunked by heading (PDFs page by page), with the file, page and line range kept on every chunk so answers can cite their source. Images get a CLIP vector, so a question can find a picture too.
Versions: every write creates a new version. Search the knowledge base as it was yesterday, or roll it back.
No server to run, no Docker, no API key. LanceDB is an embedded database (like SQLite, but for vectors), and the embedding model is small enough to run on a laptop CPU.
How it fits together
Claude Code ──stdio──▶ lancedb-kb-mcp ──▶ LanceDB tables in ./kb-data
│ ├─ items: notes, text and PDF chunks
│ │ vectors (384-dim), full-text index, versions
├─ bge-small └─ images: one row per image, CLIP vectors (512-dim)
└─ CLIP (local models, loaded on first use)The items table holds notes and document chunks. Each row has the text, a title, a project,
tags, the source file, page and line range, and its vector. Writes go through LanceDB's
merge_insert, and the full-text index is rebuilt after each write.
Images live in a second table, because their vectors come from a different model. CLIP puts a picture and a sentence describing it close together, so the question's text vector can be compared with image vectors directly. A search runs both, keeps images whose CLIP score is at least 0.28, and merges the two ranked lists by rank.
Related MCP server: HomeKB MCP Server
Quick start
You need uv and Python 3.11 or newer.
git clone <this repo> && cd lancedb-kb-mcp
uv sync
# Index the sample docs and try a search from the command line
uv run lance-kb ingest examples/docs --project demo
uv run lance-kb search "why is the queue backing up"
uv run lance-kb search "E1042"
uv run lance-kb search "what happened to the queue backlog during the outage"The first run downloads the text model (about 130 MB) and, because the samples include images, CLIP (about 580 MB) into the Hugging Face cache. After that, ingesting the six sample files (three Markdown files, a two-page PDF postmortem and two PNGs) takes a few seconds.
The first query shares no keywords with the runbook it finds; the second is an exact error code. The third comes back with a PDF page, the dashboard screenshot and a runbook section, each with its file and page or lines.
The sample files are made up for this demo. The PDF and the PNGs were rendered from HTML with a
headless browser. Six files are too few to show the difference between the search modes. On mypy's documentation (37
files, 662 chunks), searching for each of its 78 error codes on its own put the right section
first 61 times with vector search, 62 with keyword search and 69 with hybrid search. Try
--mode vector and --mode text on your own docs to see where they differ.
How well does it work?
bench/ runs three public datasets on the default models:
What | Dataset | Result |
Text | BEIR SciFact, 5,183 abstracts, 300 queries | nDCG@10 0.722 hybrid, 0.713 vector, 0.676 keyword |
PDF pages | ViDoRe V3 computer science, 945-page textbook PDF, 132 questions | right page first 74%, in the top 5 95% |
Images | Flickr30k 1k test, 1,000 photos, 5,000 captions | recall@1 0.594, recall@10 0.902 |
The bench README has the details, including what the 0.28 image cut-off hides and lets through.
Use it from Claude Code
This repo ships a project-scoped .mcp.json, so the quickest trial is to open Claude Code in this
folder:
claudeApprove the lance-kb server when asked, then try:
"Index the docs in examples/docs under project demo."
"What should I check first when the queue backlog alert fires?"
"Save a note: device cache entries expire after 15 minutes, tag it cache."
"List the knowledge base versions, then search for E1042 as it was at version 2."
To use the same knowledge base from any project, register it once at user scope:
claude mcp add lance-kb --scope user \
--env LANCE_KB_DIR=$HOME/lance-kb-data \
-- uv run --directory /path/to/lancedb-kb-mcp lancedb-kb-mcpAny other MCP client works the same way: the command is uv run lancedb-kb-mcp, over stdio.
Tools
Tool | What it does |
| Hybrid search by default; |
| One note, chunk or image with its metadata (and full text for notes and chunks). |
| Save a note and return its id. |
| Change a note; it is re-embedded. |
| Delete a note or chunk. It stays in the version history. |
| Index |
| Every version with its timestamp. |
| Make an older version current. This writes a new version, so nothing is lost. |
Every search result has a score where higher is better: the fused rank score in hybrid mode,
BM25 in text mode, cosine similarity in vector mode.
Configuration
Variable | Default | Meaning |
|
| Where the LanceDB table lives. |
|
| Any sentence-transformers model. |
|
| The image model; it must embed text and images into the same space. |
|
| Images scoring below this are left out of the results. |
| auto |
|
The model is part of your schema. Vectors from different models are not comparable, so if you
change LANCE_KB_MODEL, start a new LANCE_KB_DIR and re-ingest.
Why bge-small: 33M parameters and 384 dimensions, so it runs comfortably on a laptop CPU and
keeps the table small, while scoring well on retrieval benchmarks for its size. For non-English
content, swap in a multilingual model such as intfloat/multilingual-e5-small.
Sharing it with a team
The knowledge base is just a folder, so the simplest way to share it is to share the folder:
commit a snapshot, sync it, or copy it. Each person points LANCE_KB_DIR at their copy.
LanceDB can also open a table on object storage (s3://, gs://, az://), which lets a team
read the same table. This demo has only been tested on a local folder. If you try a shared
bucket, keep to one writer at a time (for example, a scheduled job that runs lance-kb ingest
on your docs) and let everyone else read.
Development
LANCE_KB_MODEL=hash uv run pytest
uv run ruff check src testsThe tests use the hash embedder, so they run in about a second with no model download.
Limits
One process writing at a time. Two Claude sessions writing notes to the same local folder can race; reads are fine.
The full-text index is rebuilt after every write, which is fine for thousands of rows and slow for millions. A larger deployment would batch writes and reindex on a schedule.
No vector index is built. Exact search over tens of thousands of chunks is fast; past a few hundred thousand, add one with
table.create_index(...).PDFs are read as text. Scanned PDFs have no text layer and come back empty; they need OCR.
CLIP matches what a picture looks like, not what it means. "architecture diagram of the order system" finds the diagram; "which services does an order pass through" does not. Describe the picture. The 0.28 cut-off was set on the two sample images (matches scored 0.31 to 0.33, unrelated questions up to 0.27), so check it on your own images.
Code, audio and video are not ingested.
License
Apache-2.0. See LICENSE.
Available Tools
8 toolsadd_noteC
Save a note (a decision, a finding, a how-to). Returns its id.
Inputs: text (required), title (required), tags, project. Returns: result
deleteB
Delete a note or chunk. It stays recoverable through restore_version.
Inputs: item_id (required). Returns: result
getB
Fetch one note or chunk by id, with its full text and metadata.
Inputs: item_id (required). Returns: result
ingest_folderA
Index the Markdown, text and reStructuredText files under path, chunked by heading with file and line provenance. Unchanged files are skipped; changed files are re-chunked.
Inputs: path (required), project.
list_versionsA
List the knowledge base's versions (every write creates one).
Inputs: no named parameters. Returns: result
restore_versionA
Make an older version current again (a new version is written; history is kept).
Inputs: version (required). Returns: result
searchB
Search notes and document chunks. mode is "hybrid" (vector + keyword, merged with RRF), "vector" or "text". Filter by project, kind ("note" or "chunk") or tag. Pass version to search the knowledge base as it was at that version (see list_versions).
Inputs: query (required), k, tag, kind, +3 more. Returns: result
update_noteB
Change a note's title, text, project or tags. It is re-embedded automatically.
Inputs: item_id (required), tags, text, title, +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 8 tools
Each tool has a distinct action: get by id, search by query, add/update/delete notes, ingest folders, and manage versions. Although get/search/delete all operate on notes or chunks, their purposes and inputs are clearly separable.
All names use snake_case, but the convention is mixed: add_note, update_note, ingest_folder, list_versions and restore_version are verb_noun, while get, search and delete are bare verbs. Still readable, but not a single predictable pattern.
Eight tools is well-scoped for a knowledge-base server: CRUD for notes, search, folder ingestion, and version list/restore. Each tool earns its place without obvious redundancy.
The surface covers note creation, retrieval, update, deletion, search, ingestion, and version history/restore, so core lifecycle workflows are complete. Minor gaps exist around browsing/listing notes, projects or tags directly, but search filters largely compensate.
Maintenance
Related MCP Connectors
Your own memory inside ChatGPT and Claude, with the source of every note.
Persistent memory layer for AI tools. Save and recall notes across Claude and other MCP clients.
A second brain for Claude: remembers your work, plans your day, encrypted under a key only you hold.
Long-term memory for Claude, ChatGPT, Cursor: search, save and organize notes, links, docs, videos.
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 gradedqualityCmaintenanceEnables natural language interaction with a personal knowledge base stored locally on your computer, supporting semantic search, note reading, and writing through Claude Code or mobile apps.13MIT
- AlicenseAqualityBmaintenanceEnables Claude to save, retrieve, update, search, and organize personal ideas and reusable analytical frameworks in a private SQLite-backed knowledge base. Supports local desktop use or always-on access across a user's own devices over a private network.8Apache 2.0
- FlicenseNot gradedqualityCmaintenanceEnables Claude Code to read and write local Markdown notes and to query a knowledge graph built from those notes and scanned code projects. Everything runs on localhost with no API key or installation of external services.1-