MCP Notes Server

A Model Context Protocol (MCP) server for managing notes with full CRUD operations, tagging, and search capabilities.

Features

• ✅ Create, read, update, and delete notes
• ✅ Tag-based organization and filtering
• ✅ Full-text search across notes
• ✅ Persistent storage (JSON file-based)
• ✅ Resource exposure via MCP protocol
• ✅ Compatible with Claude Desktop

Setup Instructions

Prerequisites

• Python 3.12 or higher
• pip package manager

Installation

1. Clone or download this repository

   cd "d:\Projects\AI Engineering course\MCP Server"
   

2. Install dependencies

   pip install -r requirements.txt
   

3. Configure Claude Desktop

   Edit your Claude Desktop configuration file:

   • Windows: %APPDATA%\Claude\claude_desktop_config.json
   • macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
   • Linux: ~/.config/Claude/claude_desktop_config.json

   Add the notes server configuration:

   {
     "mcpServers": {
       "notes": {
         "command": "python",
         "args": [
           "d:\\Projects\\AI Engineering course\\MCP Server\\server.py"
         ]
       }
     }
   }
   

   Note: Adjust the path to match your actual installation directory.

4. Restart Claude Desktop

   After updating the configuration, completely quit and restart Claude Desktop for the changes to take effect.

Available Tools

1. create_note

Creates a new note with content and optional metadata.

Parameters:

• content (required): The content of the note
• title (optional): Title for the note (defaults to first line of content)
• tags (optional): Array of tags for categorization

Example:

{
  "content": "Remember to buy groceries tomorrow",
  "title": "Shopping Reminder",
  "tags": ["personal", "todo"]
}

2. list_notes

Lists all notes with optional filtering and pagination.

Parameters:

• tag (optional): Filter notes by specific tag
• limit (optional): Maximum number of notes to return

Example:

{
  "tag": "work",
  "limit": 5
}

3. get_note

Retrieves the full content of a specific note.

Parameters:

• note_id (required): The ID of the note to retrieve

Example:

{
  "note_id": "1"
}

4. update_note

Updates an existing note's content, title, or tags.

Parameters:

• note_id (required): The ID of the note to update
• content (optional): New content for the note
• title (optional): New title for the note
• tags (optional): New list of tags

Example:

{
  "note_id": "1",
  "title": "Updated Title",
  "tags": ["work", "important"]
}

5. delete_note

Deletes a note by ID.

Parameters:

• note_id (required): The ID of the note to delete

Example:

{
  "note_id": "1"
}

6. search_notes

Searches notes by keyword in title or content.

Parameters:

• query (required): Search keyword or phrase
• tag (optional): Optional tag filter to narrow search

Example:

{
  "query": "meeting",
  "tag": "work"
}

Available Resources

1. note://{note_id}

Provides direct access to individual notes via URI.

Example: note://1

2. notes://list

Provides a JSON list of all notes with metadata.

Example: notes://list

Example Dialogues

Example 1: Creating and Managing a Todo List

User: Create a note for my grocery shopping list with items: milk, eggs, bread, and cheese.

Claude: I'll create a shopping list note for you.

[Uses create_note tool with content and tags]

Response: ✓ Note created successfully!

• ID: 1
• Title: Grocery Shopping List
• Tags: shopping, personal

---

User: Show me all my notes.

Claude: Let me list all your notes.

[Uses list_notes tool]

Response: Found 1 note(s):

• ID: 1 | Grocery Shopping List [shopping, personal] Items needed: milk, eggs, bread, and cheese

---

User: Add apples to my shopping list.

Claude: I'll update your shopping list to include apples.

[Uses update_note tool with note_id: "1"]

Response: ✓ Note 1 updated successfully! Updated fields: content

Example 2: Work Notes and Search

User: Create a note about tomorrow's team meeting at 10 AM. Tag it as work and important.

Claude: I'll create a note for your team meeting.

[Uses create_note tool]

Response: ✓ Note created successfully!

• ID: 2
• Title: Team Meeting - Tomorrow at 10 AM
• Tags: work, important

---

User: Create another note: "Review Q4 budget proposal before Friday meeting" with work and finance tags.

Claude: Creating your budget review note.

[Uses create_note tool]

Response: ✓ Note created successfully!

• ID: 3
• Title: Review Q4 budget proposal before Friday meeting
• Tags: work, finance

---

User: Find all my notes about meetings.

Claude: I'll search for notes containing "meeting".

[Uses search_notes tool with query: "meeting"]

Response: Found 2 note(s) matching 'meeting':

• ID: 2 | Team Meeting - Tomorrow at 10 AM [work, important] Discuss project updates and timeline...
• ID: 3 | Review Q4 budget proposal before Friday meeting [work, finance] Review Q4 budget proposal before Friday meeting

Example 3: Organizing with Tags

User: Show me all my work-related notes.

Claude: I'll list all notes tagged with "work".

[Uses list_notes tool with tag: "work"]

Response: Found 2 note(s):

• ID: 2 | Team Meeting - Tomorrow at 10 AM [work, important] Discuss project updates and timeline...
• ID: 3 | Review Q4 budget proposal before Friday meeting [work, finance] Review Q4 budget proposal before Friday meeting

---

User: Delete the meeting note, I don't need it anymore.

Claude: I'll delete note ID 2.

[Uses delete_note tool with note_id: "2"]

Response: ✓ Note 'Team Meeting - Tomorrow at 10 AM' (ID: 2) deleted successfully.

---

User: What notes do I still have?

Claude: Let me show you your remaining notes.

[Uses list_notes tool]

Response: Found 2 note(s):

• ID: 1 | Grocery Shopping List [shopping, personal] Items needed: milk, eggs, bread, cheese, and apples
• ID: 3 | Review Q4 budget proposal before Friday meeting [work, finance] Review Q4 budget proposal before Friday meeting

Known Limitations

1. Single-User Design: The server stores notes in a local JSON file without user authentication or multi-user support.

2. No Concurrent Access Protection: Multiple simultaneous operations may lead to race conditions. The server is designed for single-client (Claude Desktop) usage.

3. Limited Storage Capacity: Uses JSON file storage which may become slow with thousands of notes. Not suitable for large-scale note databases.

4. No Attachment Support: Currently only supports text content. Images, files, or rich media are not supported.

5. Basic Search: Search is case-insensitive substring matching. No support for regex, fuzzy matching, or advanced query syntax.

6. No Note History: Updates overwrite existing content without maintaining version history or undo capability.

7. No Export/Import: Currently no built-in functionality to export notes to other formats (Markdown, PDF, etc.) or import from external sources.

8. Tags Are Case-Sensitive: Tags like "Work" and "work" are treated as different tags.

9. No Nested Tags or Hierarchies: Flat tag structure only; no support for tag hierarchies or nested categories.

10. Storage File Location: The notes_storage.json file is created in the same directory as server.py. Make sure this directory is writable.

Troubleshooting

Server Not Showing Up in Claude Desktop

1. Verify the path in claude_desktop_config.json is correct and uses absolute paths
2. Check that Python 3.12+ is in your PATH
3. Restart Claude Desktop completely (quit and reopen)
4. Check Claude Desktop logs for errors

Notes Not Persisting

1. Ensure the server directory is writable
2. Check if notes_storage.json is being created in the correct location
3. Verify no permission errors in the console output

Tool Calls Failing

1. Verify all required parameters are provided
2. Check note IDs are valid strings (not integers)
3. Ensure the MCP package is properly installed

Technical Details

• Protocol: Model Context Protocol (MCP)
• Transport: stdio (standard input/output)
• Storage: JSON file (notes_storage.json)
• Python Version: 3.12+
• Dependencies: mcp (official MCP Python SDK)

License

This project is provided as-is for educational purposes.

Contributing

Feel free to submit issues or pull requests to improve the server functionality.