Notes

This MCP server lets you manage notes in Markdown format via Model Context Protocol, enabling create, read, update, delete, search, and list operations through an MCP client. It is built with Python and the FastMCP SDK, and can be run locally to serve notes as an MCP resource for clients like Claude Desktop.

How to use

Use an MCP client to interact with the Notes MCP server to create, list, read, update, delete, and search notes stored as Markdown files. You can save notes locally, filter by tags, and access all notes as a single MCP resource. The included prompts help summarize and analyze your notes.

How to install

Prerequisites include Python 3.10 or higher and a package manager for Python dependencies. Install the uv runtime (recommended) or install via pip.

# 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 MCP dependencies using uv or pip.

# Using uv (recommended)
uv pip install mcp

# Or using pip
pip install mcp

Starting and configuring the server

Save the server script and start it with the recommended runtime. Then configure Claude Desktop to load the MCP server so you can manage notes from your editor.

# Using uv (recommended)
uv run notes_server.py

# Or using python directly
python notes_server.py

Claude Desktop configuration (MCP server entry)

Add an MCP server entry to Claude Desktop configuration so the client can launch and communicate with the Notes MCP server.

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

Alternative Python command for Claude Desktop configuration

If you prefer starting the server with Python directly, configure Claude Desktop as shown.

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

Restart Claude Desktop

After adding the configuration, restart Claude Desktop to load the MCP server and enable note management through the MCP interface.

Available Tools and Operations (summary)

The Notes MCP exposes operations to create, list, read, update, delete, and search notes, all stored as Markdown files in the notes directory. Use these operations from your MCP client to manage your notes efficiently.

Notes directory and file format

Notes are stored in the notes/ directory with filenames that embed timestamp and sanitized titles, and each note is a Markdown file with metadata including Created date and Tags. This structure supports full-text search and tag-based filtering by the MCP client.

Testing and validation

A test script is provided to verify basic functionality without connecting to an LLM. Run it to create sample notes, list and filter notes, search content, and test update and delete operations.

Configuration notes

By default, notes are stored in ./notes/. To change the location, modify the NOTES_DIR variable in notes_server.py. The script uses a timestamped filename format for easy tracking and prevents accidental overwrites.

Usage examples

Create a note with a title, content in Markdown, and optional tags. List notes, read a specific note by filename, search notes by query, update notes with new content, and delete notes when needed.

Testing utilities

The included test script demonstrates note creation, listing, searching, updating, and deletion to ensure features work as expected without external dependencies.

Available tools

uv

Lightweight runtime to execute MCP servers locally via the uv toolchain.