Knowledge Base

A Personal Knowledge Base built as an MCP (Model Context Protocol) server in Python. Connect it to Claude Desktop, Claude Code, VS Code Copilot, Cursor, or any MCP-compatible client — and let your AI assistant manage your notes, tasks, and ideas.

This project teaches you the three core MCP primitives through a practical, useful application:

Primitive	What It Is	Examples in This Project
Tools	Functions the LLM can call	add_note, search_notes, add_task, update_task, get_stats
Resources	Data the LLM can browse	kb://notes, kb://tasks, kb://stats
Prompts	Reusable templates	daily_review, weekly_planning, capture_learning

Architecture

┌─────────────────────┐         stdio / SSE          ┌──────────────────────┐
│   MCP Client        │◄────────────────────────────►│  Knowledge Base      │
│   (Claude Desktop,  │    JSON-RPC 2.0 messages     │  MCP Server          │
│    Claude Code,     │                               │                      │
│    Cursor, etc.)    │                               │  ┌──────────────┐   │
│                     │    tools/call ──────────────►  │  │  12 Tools    │   │
│                     │    resources/read ──────────►  │  │  4 Resources │   │
│                     │    prompts/get ─────────────►  │  │  4 Prompts   │   │
└─────────────────────┘                               │  └──────┬───────┘   │
                                                      │         │           │
                                                      │  ┌──────▼───────┐   │
                                                      │  │   SQLite DB  │   │
                                                      │  │  + FTS5 idx  │   │
                                                      │  └──────────────┘   │
                                                      └──────────────────────┘

Quick Start

Prerequisites

• Python 3.11+
• uv (modern Python package manager)

# Install uv if you don't have it
curl -LsSf https://astral.sh/uv/install.sh | sh

1. Clone & Install

cd mcp-knowledge-base

# Create virtual environment and install dependencies
uv venv
source .venv/bin/activate   # On Windows: .venv\Scripts\activate
uv sync

2. Verify It Works

uv run test_server.py

You should see all tests pass — tools, resources, and prompts all registering correctly.

3. Connect to an MCP Client

Option A: Claude Desktop

Edit your Claude Desktop config file:

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

{
  "mcpServers": {
    "knowledge-base": {
      "command": "uv",
      "args": [
        "--directory", "/FULL/PATH/TO/mcp-knowledge-base",
        "run", "server.py"
      ]
    }
  }
}

⚠️ Replace /FULL/PATH/TO/mcp-knowledge-base with the actual absolute path.

Restart Claude Desktop. You should see a 🔨 hammer icon in the chat input — click it to see all 12 tools.

Option B: Claude Code

# From the project directory
claude mcp add knowledge-base -- uv run server.py

# Or globally
claude mcp add --scope user knowledge-base -- uv --directory /FULL/PATH/TO/mcp-knowledge-base run server.py

Then in Claude Code, your knowledge base tools are available automatically.

Option C: Cursor / VS Code

Add to your .cursor/mcp.json or VS Code MCP settings:

{
  "mcpServers": {
    "knowledge-base": {
      "command": "uv",
      "args": ["--directory", "/FULL/PATH/TO/mcp-knowledge-base", "run", "server.py"]
    }
  }
}

What You Can Do

Once connected, try these conversations with Claude:

Notes

"Save a note about what I learned about MCP today — it uses JSON-RPC 2.0, has three primitives (tools, resources, prompts), and the Python SDK uses FastMCP for the high-level API."

"Search my notes for anything about Python"

"Show me all my notes tagged with 'learning'"

Tasks

"Add a task: Build a multi-agent system with CrewAI, high priority, due next Friday"

"What are my urgent tasks?"

"Mark task #3 as done"

Prompts (Workflows)

"Run my daily review" — triggers the daily_review prompt

"Help me plan my week" — triggers weekly_planning

"I want to capture what I learned about Docker" — triggers capture_learning

Stats

"Give me an overview of my knowledge base"

Project Structure

mcp-knowledge-base/
├── server.py          # The MCP server — all tools, resources, prompts
├── test_server.py     # Test client to verify everything works
├── pyproject.toml     # Project config and dependencies
└── README.md          # You are here

Data is stored in ~/.mcp-knowledge-base/knowledge.db (SQLite with FTS5 full-text search).

Key Concepts You'll Learn

1. Tools (the most important primitive)

Tools are Python functions decorated with @mcp.tool(). The MCP SDK automatically generates the JSON schema from your type hints and docstrings:

@mcp.tool()
def add_note(title: str, content: str, tags: list[str] | None = None) -> dict:
    """Create a new note in the knowledge base."""
    ...

The LLM sees this as a callable function with typed parameters. Good docstrings = better tool use.

2. Resources (browsable data)

Resources are URIs the LLM can read, like a file system:

@mcp.resource("kb://notes/{note_id}")
def resource_single_note(note_id: int) -> str:
    """Full content of a specific note."""
    ...

3. Prompts (workflow templates)

Prompts are pre-written instructions that guide the LLM through multi-step workflows:

@mcp.prompt()
def daily_review() -> str:
    """Generate a daily review of all open tasks and recent notes."""
    return "Please review my current tasks and recent notes..."

4. Full-Text Search with FTS5

SQLite's FTS5 extension gives you fast, relevance-ranked search across all your notes — no external search engine needed.

5. Transport Modes

• stdio (default): The client spawns the server as a subprocess. Used by Claude Desktop, Claude Code, Cursor.
• SSE: Server runs as an HTTP endpoint. Used by web-based clients.

Extending This Project

Here are ideas to keep building:

1. Add a web_clip tool — save content from URLs as notes (use httpx + BeautifulSoup)
2. Add reminders — tasks with due dates that surface automatically
3. Add note linking — [[wiki-style]] links between notes
4. Add export tools — export notes as Markdown files or a PDF
5. Add an embedding-based search — use OpenAI/Anthropic embeddings for semantic search alongside FTS5
6. Add OAuth — protect your server when running over SSE (the June 2025 MCP spec update covers this)
7. Deploy to the cloud — run on Cloudflare Workers, Fly.io, or Railway with Streamable HTTP transport

Troubleshooting

Issue	Fix
Claude Desktop doesn't show tools	Restart Claude Desktop after editing config. Check the config path is correct.
ModuleNotFoundError: mcp	Run uv sync to install dependencies
Server crashes on startup	Check Python version: python --version (need 3.11+)
FTS search returns nothing	FTS index only covers notes added after the table was created
Database locked errors	Make sure only one instance of the server is running

Resources

• MCP Official Docs
• MCP Python SDK
• FastMCP — the high-level API (v1 is built into the official SDK)
• MCP Server Registry — discover community servers
• MCP Specification (Nov 2025) — the full protocol spec

License

MIT — use this however you want. Build on it, learn from it, ship it.