# Knowledge Base MCP Server
A Model Context Protocol (MCP) server for managing a personal markdown-based knowledge base. Enable AI assistants like Claude to read, search, and update your notes naturally.
## Overview
This MCP server provides AI-native access to a personal knowledge base stored as markdown files with YAML frontmatter. It allows you to:
- Create and organize notes across multiple categories
- Search through your knowledge base using natural language
- Update and maintain notes with AI assistance
- Keep all data in human-readable, portable markdown format
- Access your notes from Claude Desktop, Claude Code, or any MCP-compatible client
- **NEW:** Browse and edit notes via the included web UI
## Features
### Core Capabilities
- **7 MCP Tools** for complete knowledge base management
- `add_note` - Create new notes
- `search_notes` - Search by content, tags, or category
- `get_note` - Retrieve full note content
- `update_note` - Modify existing notes (replace or append)
- `list_notes` - List notes with optional filters
- `delete_note` - Remove notes (with backup)
- `list_categories` - View all categories and counts
- **Smart Search** with relevance scoring
- Search across titles, content, tags, and metadata
- Case-insensitive matching
- Filter by category or tags
- Ranked results by relevance
- **Flexible Organization**
- Default categories: people, recipes, meetings, procedures, tasks
- Configurable category system
- Tag-based organization
- Rich metadata support
- **Data Safety**
- Automatic backups before updates
- Atomic file writes
- Human-readable markdown format
- No vendor lock-in
- **Web UI** (Phase 2)
- Clean, dark-themed interface
- Category navigation and search
- Note creation and editing
- Authentication with JWT tokens
- Works on desktop and mobile browsers
## Installation
### Prerequisites
- Python 3.11 or higher
- `uv` package manager (recommended) or `pip`
### Install with uv (Recommended)
```bash
# Clone the repository
git clone <repository-url>
cd knowledge-base-mcp
# Install dependencies
uv sync
# The server is now ready to use
```
### Install with pip
```bash
# 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 .
```
## Running the Server
This project provides **two ways** to run the knowledge base:
### Option 1: MCP Server (for Claude Desktop/Code)
The MCP server runs via stdio and is designed to be used with Claude Desktop or Claude Code.
**Start the MCP server:**
```bash
# Using uv
uv run knowledge-base-server
# Using pip/venv
knowledge-base-server
```
The MCP server will:
- Listen on stdin/stdout for MCP protocol messages
- Wait for commands from an MCP client (like Claude Desktop)
- Not show a web interface or HTTP endpoint
**Note:** The MCP server is typically not run standalone. Instead, configure it in Claude Desktop (see Configuration section below) and let Claude Desktop manage the server lifecycle.
### Option 2: HTTP API Server (for Web/API Access)
The HTTP API server provides a web interface and REST API.
**Quick Start (No Authentication):**
By default, authentication is **disabled** for easy local development. Just run:
```bash
# Using uv
uv run knowledge-base-api
# Using pip/venv
knowledge-base-api
# Or run directly with uvicorn
uvicorn api.main:app --host 0.0.0.0 --port 8000 --reload
```
The API server will start on `http://localhost:8000` with:
- **Web UI**: `http://localhost:8000` (if web files exist)
- **API Docs**: `http://localhost:8000/docs` (Swagger UI)
- **Alternative Docs**: `http://localhost:8000/redoc` (ReDoc)
- **Health Check**: `http://localhost:8000/health`
**Using the API (No Auth):**
```bash
# Create a note
curl -X POST http://localhost:8000/notes \
-H "Content-Type: application/json" \
-d '{"title": "My Note", "content": "Hello World", "category": "people", "tags": ["test"]}'
# List all notes
curl http://localhost:8000/notes
# Search notes
curl "http://localhost:8000/search?q=hello"
```
**Optional: Enable Authentication**
To enable authentication (recommended for production), create a `.env.local` file:
```bash
# Enable authentication
REQUIRE_AUTH=true
# Required when auth is enabled
JWT_SECRET_KEY=your-secret-key-here-change-this-in-production
# Optional - AI features
ANTHROPIC_API_KEY=sk-ant-xxxxx
# Optional - custom paths
KNOWLEDGE_BASE_PATH=~/knowledge-base
CATEGORIES=people,recipes,meetings,procedures,tasks
# Optional - server settings
API_HOST=0.0.0.0
API_PORT=8000
DEBUG=false
```
**Generate a secure JWT secret:**
```bash
# On Linux/macOS
openssl rand -hex 32
# Or use Python
python -c "import secrets; print(secrets.token_hex(32))"
```
**Using the API with Authentication:**
When `REQUIRE_AUTH=true`, you need to authenticate:
1. Create an account:
```bash
curl -X POST http://localhost:8000/auth/signup \
-H "Content-Type: application/json" \
-d '{"email": "user@example.com", "password": "your-password", "full_name": "Your Name"}'
```
2. Login to get a token:
```bash
curl -X POST http://localhost:8000/auth/login \
-H "Content-Type: application/json" \
-d '{"email": "user@example.com", "password": "your-password"}'
```
3. Use the token for authenticated requests:
```bash
curl http://localhost:8000/notes \
-H "Authorization: Bearer YOUR_TOKEN_HERE"
```
## Configuration
### Environment Variables
Create a `.env` file in the project root (optional):
```bash
# Knowledge base location (default: ~/knowledge-base)
KNOWLEDGE_BASE_PATH=~/knowledge-base
# Categories (comma-separated)
CATEGORIES=people,recipes,meetings,procedures,tasks
# Server settings
SERVER_NAME=Knowledge Base
LOG_LEVEL=INFO
```
### Claude Desktop Setup
Add the server to your Claude Desktop configuration:
**macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`
**Windows**: `%APPDATA%\Claude\claude_desktop_config.json`
**Linux**: `~/.config/Claude/claude_desktop_config.json`
```json
{
"mcpServers": {
"knowledge-base": {
"command": "uv",
"args": [
"--directory",
"/absolute/path/to/knowledge-base-mcp",
"run",
"knowledge-base-server"
]
}
}
}
```
**Alternative (using pip/venv)**:
```json
{
"mcpServers": {
"knowledge-base": {
"command": "/absolute/path/to/venv/bin/python",
"args": [
"-m",
"knowledge_base_mcp.server"
],
"env": {
"KNOWLEDGE_BASE_PATH": "/path/to/your/knowledge-base"
}
}
}
}
```
After configuration, restart Claude Desktop.
## Web UI Access
The knowledge base includes a web interface for browsing and editing notes from any browser.
### Starting the Web Server
```bash
# Make sure you're in the project directory
cd knowledge-base-mcp
# Start the FastAPI server (default port 8000)
uvicorn api.main:app --host 0.0.0.0 --port 8000
# Or use the configuration from .env
python -m api.main
```
### First Time Setup
1. Open your browser to `http://localhost:8000`
2. Click "Create Account" to sign up
3. Enter your email and password (minimum 8 characters)
4. Login with your credentials
5. Start creating and organizing notes!
### Features
- **Category Navigation**: Browse notes by category with note counts
- **Full-Text Search**: Search across all notes and tags in real-time
- **Note Editor**: Clean markdown editor with auto-save warnings
- **Create/Edit/Delete**: Full CRUD operations on notes
- **Tag Management**: Organize notes with comma-separated tags
- **Responsive Design**: Works on desktop and mobile browsers
### Mobile Access
To access from your phone on the same network:
```bash
# Start server listening on all interfaces
uvicorn api.main:app --host 0.0.0.0 --port 8000
# Then access from phone using your computer's IP
# Example: http://192.168.1.100:8000
```
For remote access, consider using Tailscale or deploying to a cloud service.
## Usage
### MCP Tool Usage
### Example Interactions
#### Adding Notes
```
You: "I just met Sarah Chen at a conference. She works at Tesla on battery
tech and is interested in our AI product. Tag this as important."
Claude: [Calls add_note tool]
✓ Note 'Sarah Chen' created in people/
File: sarah-chen.md
Tags: conference, tesla, important
```
#### Searching
```
You: "Who did I meet that works on batteries?"
Claude: [Calls search_notes with query="batteries"]
Found 1 result(s):
[people] Sarah Chen [conference, tesla, batteries, important]
Battery engineer at Tesla. Met at tech conference. Interested in AI...
```
#### Retrieving Notes
```
You: "Show me my note about Sarah Chen"
Claude: [Calls get_note tool]
# Sarah Chen
**Category:** people
**Tags:** conference, tesla, batteries, important
**Date:** 2025-10-21
---
Battery engineer at Tesla...
```
#### Updating Notes
```
You: "Add to Sarah Chen's note that we scheduled a call for next Tuesday"
Claude: [Calls update_note with append=True]
✓ Note 'Sarah Chen' updated successfully
Category: people
Last updated: 2025-10-22
```
#### Quick Reference
```
You: "How long do I cook brussels sprouts in the air fryer?"
Claude: [Calls search_notes with query="brussels sprouts"]
Found 1 result(s):
[recipes] Brussels Sprouts [quick, vegetables, air-fryer]
Cook at 400°F for 15-18 minutes, shake halfway through...
```
## Knowledge Base Structure
Your knowledge base is stored as markdown files in a simple folder structure:
```
~/knowledge-base/
├── people/
│ ├── sarah-chen.md
│ ├── john-doe.md
│ └── ...
├── recipes/
│ ├── brussels-sprouts.md
│ ├── chocolate-cake.md
│ └── ...
├── meetings/
│ └── q4-planning.md
├── procedures/
│ └── onboarding-checklist.md
└── tasks/
└── launch-preparation.md
```
### Markdown Format
Each note is a markdown file with YAML frontmatter:
```markdown
---
tags: [conference, tesla, batteries, important]
date: 2025-10-21
category: people
company: Tesla
role: Battery Engineer
email: sarah.chen@tesla.com
---
# Sarah Chen
**Met:** Tech Conference 2025, Silicon Valley
**Contact:** sarah.chen@tesla.com
## Notes
Interested in our AI product for battery optimization.
Has budget approval for Q1 2026.
## Follow-up
- [ ] Send demo link by end of week
- [ ] Schedule call for next Tuesday
```
### Metadata Fields
**Required:**
- `tags`: List of tags for categorization
- `date`: Creation date (YYYY-MM-DD)
- `category`: Category folder name
**Optional (category-specific):**
- **People**: `company`, `role`, `email`, `phone`
- **Recipes**: `prep_time`, `cook_time`, `servings`
- **Meetings**: `attendees`, `meeting_date`, `location`
- **Tasks**: `priority`, `due_date`, `status`
You can add any custom metadata fields as needed.
## Development
### Running Tests
```bash
# With uv
uv run pytest
# With pip
pytest
# Run specific test file
pytest tests/test_storage.py
# Run with coverage
pytest --cov=knowledge_base_mcp tests/
```
### Project Structure
```
knowledge-base-mcp/
├── src/
│ └── knowledge_base_mcp/
│ ├── __init__.py
│ ├── server.py # MCP server and tools
│ ├── storage.py # File operations
│ ├── search.py # Search functionality
│ └── models.py # Data models
├── tests/
│ ├── test_server.py # Integration tests
│ ├── test_storage.py # Storage layer tests
│ └── test_search.py # Search tests
├── examples/
│ └── sample-notes/ # Example notes
├── pyproject.toml # Project configuration
└── README.md
```
### Adding Custom Categories
Edit your `.env` file or environment configuration:
```bash
CATEGORIES=people,recipes,meetings,procedures,tasks,books,articles,ideas
```
The server will automatically create folders for new categories.
## Troubleshooting
### Common Issues
**Server not appearing in Claude Desktop:**
- Verify the path in `claude_desktop_config.json` is absolute
- Check that the command path is correct (`uv` or python path)
- Restart Claude Desktop completely
- Check Claude Desktop logs for errors
**Notes not being created:**
- Verify `KNOWLEDGE_BASE_PATH` exists and is writable
- Check file permissions
- Ensure category is valid (use `list_categories` tool)
**Search not finding notes:**
- Verify notes have proper YAML frontmatter
- Check that tags are formatted as lists
- Try searching with simpler queries
- Use `list_notes` to see what notes exist
**Permission errors:**
- Ensure the knowledge base directory has write permissions
- On macOS, you may need to grant Claude Desktop disk access in System Preferences
### Viewing Logs
Claude Desktop logs can help diagnose issues:
- **macOS**: `~/Library/Logs/Claude/`
- **Windows**: `%APPDATA%\Claude\logs\`
- **Linux**: `~/.config/Claude/logs/`
## Use Cases
### Conference CRM
Track people you meet at conferences with contact info, notes, and follow-up tasks.
### Recipe Collection
Store recipes with tags, cook times, and personal notes about modifications.
### Meeting Notes
Keep meeting agendas, discussion points, and action items organized by topic.
### Procedure Documentation
Maintain step-by-step procedures and checklists for recurring tasks.
### Task Management
Track projects, deadlines, and task lists with priorities and status.
## Integration with Other Tools
### Obsidian
The markdown format is fully compatible with Obsidian. You can:
- Open the knowledge base in Obsidian
- Edit notes in either Obsidian or via Claude
- Use Obsidian mobile for on-the-go access
- Sync via Obsidian Sync or iCloud
### Git Version Control
Consider adding git version control to your knowledge base:
```bash
cd ~/knowledge-base
git init
git add .
git commit -m "Initial knowledge base"
```
This provides:
- Version history of all changes
- Ability to revert changes
- Backup to remote repository
- Collaboration capabilities
### File Sync
Use any file sync service:
- iCloud Drive
- Dropbox
- Google Drive
- Syncthing
## Roadmap
### Phase 2 Features (Planned)
- HTTP API for web and mobile access
- Web UI for browsing and editing
- AI pendant integration via webhooks
- Automatic summarization and insights
- Calendar integration
- Email integration
### Future Considerations
- Multi-user support
- Real-time collaboration
- Advanced search with embeddings
- Automatic tagging suggestions
- Template system for note types
## Contributing
Contributions are welcome! Please:
1. Fork the repository
2. Create a feature branch
3. Add tests for new functionality
4. Ensure all tests pass
5. Submit a pull request
## License
MIT License - see LICENSE file for details
## Support
- Report issues: [GitHub Issues]
- Documentation: [MCP Documentation](https://modelcontextprotocol.io)
- Community: [MCP Discord]
## Acknowledgments
Built with:
- [Model Context Protocol](https://modelcontextprotocol.io)
- [MCP Python SDK](https://github.com/modelcontextprotocol/python-sdk)
- [PyYAML](https://pyyaml.org/)
---
Made with Claude Code