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

• Web Interface: Browse your notes in a wiki-style web interface with backlinks and tag navigation

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"

Web Interface

In addition to the MCP server integration with Claude Desktop, this project includes a Flask-based web interface for browsing your notes in a wiki-style format.

Features

• Wiki Links: Create connections between notes using [[Note Title]] syntax

• Backlinks: See which notes link to the current note

• Tag Navigation: Browse notes by category, type, priority, and topics

• Search: Full-text search across titles and content

• Recent Notes: View recently updated notes

• Markdown Rendering: Beautiful rendering with syntax highlighting for code blocks

Running the Web Interface

1. Install web dependencies (if not already installed):

   python3.11 -m pip install -r requirements.txt

2. Start the web server:

   python3.11 web_server.py

3. Open your browser: Visit http://localhost:5000

The web interface reads directly from the same notes.json file used by the MCP server, so any changes made in Claude Desktop appear immediately when you refresh the page.

For detailed information about the web interface features and usage, see WIKI_README.md.

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:

MCP Server:

• 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 archiving/soft delete

• Tag aliases and synonyms

• Bulk operations (bulk update, bulk export with filters)

• Note templates

Web Interface:

• Graph visualization of note connections

• Live editing capabilities

• Dark mode theme toggle

• Advanced search with regex and tag combinations

• Auto-complete for wiki links

• Tag management UI

License

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