You can run an MCP server that acts as a personal knowledge base powered by Markdown files. It provides AI-native access to your notes for searching, creating, updating, and organizing content across categories, while keeping your data in a human-readable format and offering a web UI for convenient editing and browsing.

How to use

You use an MCP client to connect to the knowledge base server. There are two ways you can run and interact with the server depending on your needs:

How to install

Prerequisites you need before installation are Python 3.11 or higher and a runtime for running MCP servers.

Option 1: Install with uv (recommended) by cloning the project, installing dependencies with uv, and starting the server.

# Clone the repository
git clone <repository-url>
cd knowledge-base-mcp

# Install dependencies
uv sync

# The server is now ready to use

Option 2: Install with pip for development mode after cloning the project and creating a virtual environment.

# Clone the repository
git clone <repository-url>
cd knowledge-base-mcp

# Create virtual environment
python -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate

# Install in development mode
pip install -e .

Additional sections

Configuration and runtime options are provided to support different use cases. You can run a standard MCP server for Claude Desktop/Code via a stdio interface, or expose an HTTP API server for web access. Environment variables let you tailor paths, categories, and security settings.

Starting the MCP server via stdio (for Claude Desktop/Code):

uv run knowledge-base-server

This starts the MCP server that listens for messages from MCP clients over standard input/output.

Starting the HTTP API server (for web access):

Quick start (No authentication by default)

uv run knowledge-base-api

or

knowledge-base-api

Or run directly with the web server

uvicorn api.main:app --host 0.0.0.0 --port 8000 --reload

## Available tools

### add\_note

Create a new note with a title, content, category, and optional metadata like tags and date.

### search\_notes

Search notes by content, tags, or category with optional filters and relevance ranking.

### get\_note

Retrieve the full content of a single note, including metadata and body.

### update\_note

Modify an existing note, with options to replace or append content.

### list\_notes

List notes with optional filters such as category and tags.

### delete\_note

Remove a note, with automatic backup to prevent data loss.

### list\_categories

Show all categories and their note counts.