kb-mcp-server
Exposes a /metrics endpoint in Prometheus text exposition format, reporting request counts by method/path/status and process uptime for scraping by Prometheus.
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-server search my notes for meeting recaps"
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-server
A local-first MCP (Model Context Protocol) server exposing a searchable knowledge base of notes, backed by SQLite + FTS5. No external API keys required.
Status: under construction — this README grows as the project does. See
ARCHITECTURE.md for design decisions and CHANGELOG.md for what's landed so far.
Prerequisites
uv (manages the Python interpreter and dependencies — you do not need Python 3.12 pre-installed,
uvwill fetch it)
Related MCP server: Notebook MCP Server
Setup
cd project-1-mcp-server
uv sync --devThis creates a .venv/ and installs both runtime and dev dependencies, pinned via
uv.lock.
Running checks locally
uv run ruff check . # lint
uv run ruff format --check . # format check
uv run mypy # type check (strict)
uv run pytest -v # testsRunning the server
Over stdio (the transport Claude Desktop/Code use):
uv run kb-mcp-serverBy default it stores notes in ./data/kb.sqlite3 (override with KB_DB_PATH).
It speaks newline-delimited JSON-RPC on stdin/stdout — it's not meant to be
run interactively in a terminal. To poke at it directly, use the
MCP Inspector:
npx @modelcontextprotocol/inspector uv run kb-mcp-serverOver Streamable HTTP (for remote clients — requires a bearer token):
KB_TRANSPORT=http KB_AUTH_TOKEN=$(openssl rand -hex 32) uv run kb-mcp-server
# defaults to http://127.0.0.1:8000/mcp; override with KB_HTTP_HOST/KB_HTTP_PORTUnauthenticated requests to /mcp or /metrics get 401. /health (no
auth required — for load balancer/k8s liveness probes) checks real database
connectivity, not just that the process is up:
curl http://127.0.0.1:8000/health
curl -H "Authorization: Bearer $KB_AUTH_TOKEN" http://127.0.0.1:8000/metrics/metrics is exposed in Prometheus text exposition format (request counts
by method/path/status, process uptime).
Currently implemented tools: create_note, get_note, update_note,
delete_note, search_notes.
Currently implemented resources: notes://recent{?limit} (recently updated
notes), notes://{note_id} (a single note).
Currently implemented prompts: summarize_note, draft_reply.
Running with Docker
The image always runs the HTTP transport (stdio doesn't make sense for a detached container — there's no host process piping its stdin/stdout).
cp .env.example .env
# edit .env: set KB_AUTH_TOKEN=$(openssl rand -hex 32)
docker compose up --builddocker compose auto-loads .env from the same directory — the exact file
uv run also reads locally, so there's one place to set the token either
way. Notes persist in a named volume (kb-data) across container restarts.
Without KB_AUTH_TOKEN set, docker compose up refuses to start at all
(fails at config-interpolation time, before Docker is even invoked) rather
than launching something unauthenticated.
To run the container directly, without compose:
docker build -t kb-mcp-server .
docker run -d -p 8000:8000 -e KB_AUTH_TOKEN=$(openssl rand -hex 32) \
-v kb-data:/app/data --name kb-mcp-server kb-mcp-serverThe image runs as a non-root user (uid 1000), ships a HEALTHCHECK hitting
/health, and forwards SIGTERM correctly on docker stop/docker compose down (exec-form CMD, so the app is PID 1, not a shell wrapping
it).
Registering with an MCP host
Claude Code
claude mcp add kb-notes -s user -- uv run --directory /absolute/path/to/project-1-mcp-server kb-mcp-server--directory matters: Claude Code spawns the command without first cd-ing
into the project, so uv run kb-mcp-server alone (relying on an implicit
cwd) would fail to find pyproject.toml. -s user registers it for every
project (a personal notes tool isn't tied to any one codebase) — use
-s local (the default) to scope it to just the directory you're in, or
-s project to check a shared .mcp.json into a repo for teammates.
Verify with claude mcp get kb-notes — it actually spawns the server and
completes the MCP handshake, so ✔ Connected means it really works, not
just that the config was written. Then, in a new Claude Code session
(MCP servers load at session start, not hot-reloaded into a running one),
ask it to create and search a note.
Claude Desktop
Add an entry to claude_desktop_config.json (macOS:
~/Library/Application Support/Claude/claude_desktop_config.json):
{
"mcpServers": {
"kb-notes": {
"command": "uv",
"args": [
"--directory",
"/absolute/path/to/project-1-mcp-server",
"run",
"kb-mcp-server"
]
}
}
}Restart Claude Desktop for it to pick up the change, then look for the tools under the 🔌 (plug/MCP) icon in a chat.
Available Tools
5 toolscreate_noteC
Create a new note with a title and body, and return the saved note.
Inputs: body (required), title (required). Returns: A note as returned to callers -- immutable, already-valid.
delete_noteC
Delete a note by its id.
Inputs: note_id (required). Returns: Confirmation that a note was deleted -- a presentation-only shape, not a domain…
get_noteB
Retrieve a single note by its id.
Inputs: note_id (required). Returns: A note as returned to callers -- immutable, already-valid.
search_notesA
Full-text search over note titles and bodies, ranked by relevance. Supports FTS5 syntax: quote a phrase for an exact match, combine terms with AND/OR/NOT, or prefix-match with an asterisk (e.g. kaf*).
Inputs: query (required), limit, offset. Returns: A page of search results, self-describing enough to render pagination UI/tool o…
update_noteC
Replace an existing note's title and body.
Inputs: body (required), title (required), note_id (required). Returns: A note as returned to callers -- immutable, already-valid.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 5 tools
Each tool targets a distinct action on a single note resource: create, retrieve, update, delete, and search. There is no overlap or ambiguity; an agent can easily select the correct tool.
All tool names follow a consistent verb_noun pattern in snake_case: create_note, get_note, update_note, delete_note, search_notes. The convention is predictable and readable.
With 5 tools, the set is well-scoped for a note management server. It covers essential operations without bloat, and each tool earns its place.
The server provides full CRUD plus full-text search, covering the core lifecycle. However, it lacks an explicit 'list all notes' operation, which could be a minor gap for some workflows.
Maintenance
Related MCP Connectors
Persistent memory, hybrid search and a goal graph for AI agents, over stdio or remote HTTP.
A self-hostable feed of reminders, learnings and work that Claude and ChatGPT can read and write
Personal context for every AI: search, read, and write back to your private Markdown library.
Google Keep-style notes app with an MCP server for AI agents to read/write notes.
Related MCP Servers
- FlicenseBqualityDmaintenanceEnables indexing and retrieving notes with full-text search using SQLite, plus building knowledge graphs to find relationships between concepts. Supports natural language note management, tagging, and semantic connections.16-
- FlicenseNot gradedqualityDmaintenanceEnables to create notebooks and notes with tags, and perform full-text search across notes using FTS5 syntax, all stored locally in SQLite.-
- AlicenseAqualityBmaintenanceShared memory for AI coding agents (Claude Code, Codex, Cursor and others) in one local SQLite file, over MCP or REST. Every note records which agent wrote it and keeps its history; writes that match known prompt-injection patterns are held for your review; you can roll back everything one writer did. Runs on your machine, no cloud or API keys, MIT licensed.91,498 npm9MIT
- AlicenseNot gradedqualityCmaintenanceA local stdio server that lets AI coding agents capture new notes, propose cited edits to existing records, recall cited evidence, and fetch individual records from a shared revisioned SQLite memory store. A read-only mode restricts a connection to recall and retrieval only.Apache 2.0