📝 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

# MacOS/Linux
curl -LsSf https://astral.sh/uv/install.sh | sh

# Windows
powershell -c "irm https://astral.sh/uv/install.ps1 | iex"

# Or via pip
pip install uv

Install Dependencies

# Using uv (recommended)
uv pip install mcp

# Or using pip
pip install mcp

🚀 Quick Start

1. Save the Server

Save notes_server.py in your desired directory.

2. Run the Server

# Using uv (recommended)
uv run notes_server.py

# Or using python directly
python notes_server.py

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

{
  "mcpServers": {
    "notes": {
      "command": "uv",
      "args": [
        "--directory",
        "/absolute/path/to/notes-mcp-server",
        "run",
        "notes_server.py"
      ]
    }
  }
}

Alternative with Python:

{
  "mcpServers": {
    "notes": {
      "command": "python",
      "args": ["/absolute/path/to/notes_server.py"]
    }
  }
}

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:

Create a note titled "Project Ideas" with content "1. Build MCP server\n2. Add search" and tags "work, ideas"

list_notes

List all notes with their titles and creation dates.

Parameters:

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

Example:

List all notes
List notes with tag "work"

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:

Read note "20241106_120000_project_ideas.md"

search_notes

Search for notes containing specific text.

Parameters:

• query (string): Search query

Example:

Search notes for "Python"

update_note

Append content to an existing note with timestamp.

Parameters:

• filename (string): The filename of the note

• content (string): Content to append

Example:

Update note "20241106_120000_project_ideas.md" with "3. Implement testing"

delete_note

Delete a note permanently.

Parameters:

• filename (string): The filename of the note

Example:

Delete note "20241106_120000_old_note.md"

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

notes/
├── 20241106_120000_project_ideas.md
├── 20241106_130000_shopping_list.md
└── 20241106_140000_python_notes.md

Note Format

Each note is a Markdown file with metadata:

# Project Ideas

**Created:** 2024-11-06 12:00:00
**Tags:** work, ideas

---

1. Build MCP server
2. Add search functionality
3. Implement testing

🧪 Testing

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

python test_notes_server.py

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:

NOTES_DIR = os.path.join(os.path.dirname(__file__), "notes")

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

"Create a note titled 'Meeting Notes' with content 'Discussed Q4 goals' and tags 'work, meetings'"

Find Related Notes

"Search my notes for anything related to 'Python'"

Review Notes by Category

"List all notes tagged with 'personal'"

Summarize Notes

"Use the summarize_notes_prompt to analyze all my 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