Notes MCP Server

# 📝 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](https://github.com/astral-sh/uv) package manager ### Install uv ```bash # 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 ```bash # 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 ```bash # 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` ```json { "mcpServers": { "notes": { "command": "uv", "args": [ "--directory", "/absolute/path/to/notes-mcp-server", "run", "notes_server.py" ] } } } ``` **Alternative with Python:** ```json { "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: ```markdown # 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: ```bash 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`: ```python 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](https://modelcontextprotocol.io/) - [FastMCP Python SDK](https://github.com/modelcontextprotocol/python-sdk) - [Claude Desktop](https://claude.ai/download) ## ⚠️ 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](https://github.com/modelcontextprotocol/python-sdk)