📝 Notes MCP Server

A Model Context Protocol (MCP) server for managing notes in Markdown format. Built with Python and the FastMCP SDK.

🌟 Features

• Create Notes: Create new Markdown notes with titles, content, and tags

• List & Filter: View all notes or filter by specific tags

• Search: Full-text search across all notes with context preview

• Update: Append content to existing notes with timestamps

• Delete: Remove notes when no longer needed

• Resources: Access all notes as a single MCP resource

• AI Prompts: Built-in prompt for analyzing and summarizing notes

📦 Installation

Prerequisites

• Python 3.10 or higher

• uv package manager

Install uv

Install Dependencies

🚀 Quick Start

1. Save the Server

Save notes_server.py in your desired directory.

2. Run the Server

3. Configure in Claude Desktop

Add to your claude_desktop_config.json:

MacOS: ~/Library/Application Support/Claude/claude_desktop_config.json Windows: %APPDATA%/Claude/claude_desktop_config.json

Alternative with Python:

4. Restart Claude Desktop

After adding the configuration, restart Claude Desktop to load the MCP server.

🛠️ Available Tools

create_note

Create a new note with title, content, and optional tags.

Parameters:

• title (string): Note title

• content (string): Note content in Markdown

• tags (string, optional): Comma-separated tags

Example:

list_notes

List all notes with their titles and creation dates.

Parameters:

• tag (string, optional): Filter by specific tag

Example:

read_note

Read the full content of a specific note.

Parameters:

• filename (string): The filename of the note (e.g., 20241106_120000_project_ideas.md)

Example:

search_notes

Search for notes containing specific text.

Parameters:

• query (string): Search query

Example:

update_note

Append content to an existing note with timestamp.

Parameters:

• filename (string): The filename of the note

• content (string): Content to append

Example:

delete_note

Delete a note permanently.

Parameters:

• filename (string): The filename of the note

Example:

📚 Resources

notes://all

Access all notes as a combined resource. Useful for context-aware operations.

💡 Prompts

summarize_notes_prompt

Generates a prompt for AI to analyze all notes and provide:

1. Summary of main themes

2. Recurring ideas or patterns

3. Important action items

4. Recommendations for organization

📁 File Structure

Notes are stored in the notes/ directory with the following format:

Note Format

Each note is a Markdown file with metadata:

🧪 Testing

A test script is included to verify functionality without connecting to an LLM:

The test script will:

• Create sample notes

• List and filter notes

• Search for content

• Update and delete notes

• Test all features

🔧 Configuration

Notes Directory

By default, notes are stored in ./notes/. To change the location, modify the NOTES_DIR variable in notes_server.py:

Filename Generation

Notes are saved with timestamps and sanitized titles:

• Format: YYYYMMDD_HHMMSS_sanitized_title.md

• Max title length: 100 characters

• Special characters are removed

• Spaces converted to underscores

📝 Usage Examples

Create a Note

Find Related Notes

Review Notes by Category

Summarize Notes

🤝 Contributing

Contributions are welcome! Feel free to:

• Report bugs

• Suggest new features

• Submit pull requests

📄 License

This project is open source and available under the MIT License.

🔗 Resources

• Model Context Protocol Documentation

• FastMCP Python SDK

• Claude Desktop

⚠️ Limitations

• Text-based notes only (no file attachments)

• No note encryption

• Single notes directory (no subdirectories)

• UTF-8 encoding only

💬 Support

For issues or questions:

1. Check the test script output for debugging

2. Review the notes directory permissions

3. Ensure Python 3.10+ is installed

4. Verify MCP SDK installation

Made with ❤️ using FastMCP