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:

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

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.