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

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

Installation

Prerequisites

• Python 3.11 or higher
• uv package manager (recommended) or pip

Install with uv (Recommended)

# 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

# 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 .

Configuration

Environment Variables

Create a .env file in the project root (optional):

# 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

{
  "mcpServers": {
    "knowledge-base": {
      "command": "uv",
      "args": [
        "--directory",
        "/absolute/path/to/knowledge-base-mcp",
        "run",
        "knowledge-base-server"
      ]
    }
  }
}

Alternative (using pip/venv):

{
  "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.

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:

---
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

# 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:

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:

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
• Community: [MCP Discord]

Acknowledgments

Built with:

• Model Context Protocol
• MCP Python SDK
• PyYAML

---

Made with Claude Code