🧠 MCP Knowledge Base Server

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:

Add a web_clip tool — save content from URLs as notes (use httpx + BeautifulSoup)
Add reminders — tasks with due dates that surface automatically
Add note linking — [[wiki-style]] links between notes
Add export tools — export notes as Markdown files or a PDF
Add an embedding-based search — use OpenAI/Anthropic embeddings for semantic search alongside FTS5
Add OAuth — protect your server when running over SSE (the June 2025 MCP spec update covers this)
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.

mcp-knowledge-base