MCP Note-Taking Server

A Model Context Protocol (MCP) server for managing personal notes with structured tagging and markdown support. This server integrates with Claude Desktop to provide seamless note-taking capabilities during AI conversations.

Features

• Structured Tagging: Controlled vocabulary for categories, types, priorities, and topics with dynamic schema management
• Markdown Support: Write rich notes with markdown formatting
• Advanced Search: Find notes using tag filters, title search, and date range filtering
• Export Capabilities: Export individual notes or entire collections to markdown files
• Dynamic Schema: Add new tags to any dimension programmatically
• JSON Storage: Simple file-based persistence with atomic writes
• MCP Integration: Works natively with Claude Desktop via stdio transport

Installation

Prerequisites

• Python 3.10 or higher (required by MCP SDK)
• Claude Desktop application

Check your Python version:

python3 --version

If you have Python 3.9 or older, install a newer version:

• macOS: brew install python@3.11 (requires Homebrew)
• Alternative: Download from python.org

Setup

1. Clone or download this repository

2. Install dependencies:

   # If you installed Python 3.11 via Homebrew, use:
   python3.11 -m pip install -r requirements.txt
   
   # Or use whichever Python 3.10+ you have installed
   

3. Configure Claude Desktop:

   Edit your Claude Desktop configuration file:

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

   Add the following configuration:

   {
     "mcpServers": {
       "notes": {
         "command": "python3.11",
         "args": ["/absolute/path/to/MCPNotes/server.py"]
       }
     }
   }
   

   Important:

   • Replace python3.11 with your Python 3.10+ command (use which python3.11 to verify)
   • Replace /absolute/path/to/MCPNotes/server.py with the actual path to your server.py file

4. Restart Claude Desktop to load the server

5. Verify installation: Open Claude Desktop and ask: "What tools do you have available?" You should see the note-taking tools listed.

Data Model

Note Structure

Each note contains:

• id: Unique UUID
• title: Note title
• content: Markdown-formatted content
• tags: Structured tags (category, type, priority, topics)
• created: ISO-8601 timestamp
• updated: ISO-8601 timestamp

Tag Schema

The default tag schema includes:

• category (required, exactly one): work, personal, learning
• type (required, exactly one): project, idea, reference, todo, note
• priority (required, exactly one): active, soon, someday, eventually, maybe, not-actionable
• topics (optional, zero or more): mcp, ai, coding, design

You can dynamically add new tags to any dimension using the add_tags_to_schema tool, or manually edit notes.json.

Available Tools

1. get_tag_schema

Get the complete tag schema showing all valid tags.

Example: "Show me the tag schema"

2. create_note

Create a new note with validated tags.

Example: "Create a note titled 'MCP Server Ideas' with content 'Build a notes server using MCP', category: learning, type: project, priority: active, topics: mcp, coding"

3. update_note

Update an existing note (partial updates supported).

Example: "Update note [id] and change the priority to 'soon'"

4. delete_note

Delete a note by ID.

Example: "Delete note [id]"

5. read_note

Read the full content of a specific note.

Example: "Show me note [id]"

6. find_notes_by_tags

Search notes using tag filtering, title search, and date filters (AND logic across all filters, OR within topics).

Parameters:

• Tag filters: category, type, priority, topics
• Title search: title_contains (case-insensitive substring match)
• Date filters: created_after, created_before, updated_after, updated_before (ISO-8601 timestamps)

Examples:

• "Find all notes with category 'work' and priority 'active'"
• "Find all notes about mcp or ai topics"
• "Find notes with 'MCP' in the title"
• "Find notes created after 2025-01-01"
• "Show me notes updated in the last week"
• "Show me all notes" (no filters = return all)

7. list_tags

List all tags currently in use with counts.

Example: "What tags am I using in my notes?"

8. add_tags_to_schema

Add new tags to a schema dimension dynamically.

Parameters:

• dimension: One of category, type, priority, or topics
• tags: Array of tag values to add

Examples:

• "Add a new category called 'research'"
• "Add 'urgent' and 'backlog' to the priority dimension"
• "Add topics: python, javascript, rust"

9. export_note_to_markdown

Export a single note to a markdown file.

Parameters:

• id: Note UUID to export
• output_path: Optional custom output file path (auto-generated if not provided)

Examples:

• "Export note [id] to markdown"
• "Export this note to /Users/me/Desktop/note.md"

10. export_all_notes_to_markdown

Export all notes to markdown files in a directory.

Parameters:

• output_dir: Optional output directory path (defaults to exported_notes/)

Examples:

• "Export all my notes to markdown"
• "Export all notes to /Users/me/Desktop/my_notes"

Usage Examples

Here are some natural ways to interact with your notes in Claude Desktop:

Creating notes:

• "I want to take a note about the MCP protocol I'm learning"
• "Create a note for my project idea"

Finding notes:

• "Show me all my active work projects"
• "What learning notes do I have?"
• "Find notes about ai or coding"
• "Find notes with 'Python' in the title"
• "Show me notes I created this week"
• "Find notes updated after January 1st"

Managing notes:

• "Change the priority of note [id] to 'soon'"
• "Update the content of my MCP note"
• "Delete that old note"

Organizing:

• "What tags am I using?"
• "Show me the tag schema"
• "List all my active todos"
• "Add a new category called 'health'"
• "Add 'python' and 'rust' to my topics"

Exporting:

• "Export all my notes to markdown"
• "Export note [id] to a markdown file"
• "Export all notes to my Desktop"

File Structure

mcp-notes/
├── notes.json          # Data storage (auto-created)
├── server.py           # Main MCP server
├── README.md           # This file
└── requirements.txt    # Python dependencies

Data Storage

• All notes are stored in notes.json in the same directory as server.py
• The file is automatically created on first run with the default schema
• Atomic writes prevent data corruption
• All data persists across server restarts

Troubleshooting

Server not appearing in Claude Desktop:

• Verify the path in claude_desktop_config.json is absolute and correct
• Check that Python is in your PATH
• Restart Claude Desktop completely

Tag validation errors:

• Use get_tag_schema to see valid tags
• Ensure required tags (category, type, priority) are provided
• Check that all tags match the schema exactly (case-sensitive)

Notes not persisting:

• Verify notes.json exists and is writable
• Check file permissions on the directory

Future Enhancements

Potential improvements for future versions:

• Full-text search within note content (search across markdown)
• Import existing markdown files as notes
• SQLite backend for better performance with large note collections
• Note linking and backlinks
• Note archiving/soft delete
• Tag aliases and synonyms
• Bulk operations (bulk update, bulk export with filters)
• Note templates

License

GPL-3.0 License - feel free to modify and extend this server for your needs.