Notes

MCP Notes Server

This is an MCP (Model Context Protocol) server implementation that manages markdown notes in a given directory. The server provides functionality to create, read, and update markdown notes using the stdio transport.

Features

• Create new markdown notes
• Read existing markdown notes
• Update existing markdown notes
• List all notes in the vault
• Automatic file management in the specified directory
• Proper error handling and logging
• Timestamp tracking for note creation and modification
• JSON Schema validation for all operations

Server Capabilities

The server implements the following capabilities:

• Version: 1.0.0
• Name: Notes MCP Server
• Description: A server for managing markdown notes in an given directory
• Supported Transports: stdio

Resources

The server provides the following resource:

• Properties:
  • path: The path to the vault
  • note_count: The total number of notes in the vault

Tools

The server implements the following MCP tools:

create_note

Creates a new markdown note.

Parameters:

• title: The title of the note (required)
• content: The content of the note (optional, defaults to empty string)

Returns:

• filename: The name of the created file
• path: The full path to the created file
• created_at: ISO timestamp of creation

read_note

Reads an existing markdown note.

Parameters:

• title: The title of the note to read (required)

Returns:

• title: The title of the note
• content: The content of the note
• path: The full path to the file
• created_at: ISO timestamp of creation
• modified_at: ISO timestamp of last modification

update_note

Updates an existing markdown note.

Parameters:

• title: The title of the note to update (required)
• content: The new content for the note (optional, defaults to empty string)

Returns:

• filename: The name of the updated file
• path: The full path to the file
• updated_at: ISO timestamp of update

list_notes

Lists all markdown notes in the vault.

Parameters: None

Returns:

• notes: Array of note objects, each containing:
  • title: The title of the note
  • path: The full path to the file
  • created_at: ISO timestamp of creation
  • modified_at: ISO timestamp of last modification
• total: Total number of notes

Setup

1. Install the required dependencies:

pip install -r requirements.txt

2. Configure the server to work within the given directory on line 110 of main.py by editing the notes_dir property:

3. Configure Cursor to use the MCP server:

   • The configuration file is located at .cursor/mcp.json
   • Cursor will automatically detect and use this configuration
   • The server is configured to run with Python and proper UTF-8 encoding

Running the Server

The server will automatically start when Cursor loads the project. You can also run it manually:

python main.py

The server will start and listen for MCP requests through stdin/stdout. All operations are logged with appropriate levels (info/error) for debugging and monitoring.

Error Handling

The server implements proper error handling for various scenarios:

• Missing required parameters
• File already exists
• File not found
• General exceptions

All errors are logged and returned with appropriate error codes and messages.

Configuration Details

The MCP server is configured in .cursor/mcp.json with the following settings:

{
  "mcpServers": {
    "notes-server": {
      "command": "python",
      "args": ["main.py"],
      "env": {
        "PYTHONIOENCODING": "utf-8"
      }
    }
  }
}

To add the MCP as globally used, add it to the .cursor folder in your user directory, or go to Cursor Settings -> MCP -> Add New Global MCP Server -> copy/paste the mcp.json in this project to the new file -> Update the args to point to main.py

This configuration:

• Names the server "notes-server"
• Uses Python to run the server
• Sets UTF-8 encoding for proper character handling