MCP Knowledge Base Server

Give your AI assistant a long-term memory. Drop markdown files into a folder — Claude instantly knows your notes, docs, and code snippets.

What is this?

MCP Knowledge Base Server is a personal knowledge base that connects directly to AI assistants like Claude Desktop and Cursor. It turns a local folder of markdown files into a queryable, semantically searchable memory layer — without any cloud infrastructure or external databases.

It works over the Model Context Protocol (MCP), a standard that lets AI assistants call tools and retrieve data from local servers. When you ask Claude "what do my notes say about deployment?", it uses this server to run a semantic similarity search over your embedded documents and return the most relevant chunks — all locally, in milliseconds.

Under the hood, it uses OpenAI's text-embedding-3-small model to generate vector embeddings for your markdown content, stores them in a local SQLite database, and performs cosine similarity search to find the most relevant material. The server auto-indexes on startup (only re-embedding changed files), so your knowledge base stays fresh with zero manual work.

Features

• 🔍 Semantic search across your knowledge base using OpenAI embeddings
• 📄 Full document retrieval by title or file path
• 🏷️ Topic browser — list all tags and categories with document counts
• ✍️ AI-driven note creation — let Claude write notes back to your KB
• ⚡ Incremental indexing — only re-embeds changed files on startup
• 🗄️ Zero-dependency storage — SQLite, no external DB required
• 🔧 Simple CLI — mcp-kb index, mcp-kb stats, mcp-kb serve

Prerequisites

• Node.js >= 18
• An OpenAI API key (for embeddings — uses text-embedding-3-small, ~$0.02/1M tokens)

Quick Start

1. Clone and install

git clone https://github.com/YOUR_USERNAME/mcp-knowledge-base.git
cd mcp-knowledge-base
npm install

2. Set your OpenAI API key

cp .env.example .env
# Edit .env and add your key:
# OPENAI_API_KEY=sk-...

3. Add your markdown files

Drop .md files into the knowledge/ directory. They can have YAML frontmatter:

---
title: "My Note"
tags: [typescript, backend]
category: "guides"
---

# Content here

4. Index your knowledge base

npm run build
npx mcp-kb index

5. Configure Claude Desktop

Add to your claude_desktop_config.json (location below):

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "knowledge-base": {
      "command": "node",
      "args": ["/absolute/path/to/mcp-knowledge-base/dist/server.cjs"],
      "env": {
        "OPENAI_API_KEY": "sk-your-key-here"
      }
    }
  }
}

Then restart Claude Desktop.

CLI Reference

Command	Description
npx mcp-kb index	Index all markdown files in the knowledge directory
npx mcp-kb index --force	Force re-index all files (ignores change detection)
npx mcp-kb index --dry-run	Preview what would be indexed without API calls
npx mcp-kb stats	Show KB statistics (docs, chunks, tags, DB size)
npx mcp-kb serve	Start the MCP server manually

MCP Tools

Once connected, Claude has access to these tools:

Tool	Description
search_knowledge	Semantic search — ask in natural language
get_document	Retrieve a full document by title or path
list_topics	Browse all tags and categories
add_note	Let Claude write a new note to your KB

Example Prompts

Once configured in Claude Desktop, try:

• "What do my notes say about authentication middleware?"
• "Show me everything tagged 'typescript'"
• "What topics are covered in my knowledge base?"
• "Write a summary of today's meeting and save it as a note"
• "Get the full content of my deployment guide"

Configuration

Edit config.json to customize behavior:

{
  "knowledgeDir": "./knowledge",
  "embeddingModel": "text-embedding-3-small",
  "chunkSize": 500,
  "chunkOverlap": 50,
  "topN": 5,
  "openaiApiKey": "$OPENAI_API_KEY"
}

Field	Default	Description
knowledgeDir	./knowledge	Directory to scan for .md files
embeddingModel	text-embedding-3-small	OpenAI model for embeddings
chunkSize	500	Max tokens per chunk
chunkOverlap	50	Overlap tokens between chunks
topN	5	Default number of search results

Architecture

The server follows a clean three-layer architecture: Ingestion scans markdown files, parses YAML frontmatter, splits content into overlapping chunks, and generates OpenAI embeddings — only for files that have changed since the last run (via SHA-256 hashing). Storage persists documents, chunks, and embeddings in a local SQLite database using WAL mode for write performance and an in-memory cache for fast similarity lookups. MCP Server exposes four tools to the AI assistant via stdio transport, handling all search, retrieval, and write operations.

Tech Stack

• Runtime: Node.js + TypeScript
• MCP SDK: @modelcontextprotocol/sdk
• Embeddings: OpenAI text-embedding-3-small
• Storage: better-sqlite3 (WAL mode)
• Markdown: gray-matter + markdown-it
• CLI: commander
• Build: tsup
• Tests: vitest

Development

npm run build     # compile TypeScript
npm test          # run tests
npm run dev       # watch mode build

Limitations & Roadmap

Current limitations (v1):

• Markdown files only (.md)
• In-process similarity search — works well up to ~10k chunks
• Single knowledge base (no namespacing)

Planned for future versions:

• pgvector support for large knowledge bases
• Multi-format ingestion (PDF, HTML, plain text)
• Namespace support (work/personal/project-x)
• Local embedding models (offline operation)
• Obsidian vault compatibility with [[wikilinks]]

License

MIT — see LICENSE