cau1k/notes-mcp

Notes MCP Server

A simple notes management MCP (Model Context Protocol) server built with FastMCP. This server allows you to create, read, update, delete, and search notes organized by categories.

Features

• Create notes with titles, content, and categories
• List all notes or filter by category
• Read specific notes
• Update existing notes
• Delete notes
• Search notes by content or title
• Organize notes in categories (folders)

Installation

1. Make sure you have Python 3.10+ installed
2. Install the project using uv:

uv sync

Usage

Running the Server

uv run notes-mcp

The server will start and listen for MCP connections.

Available Tools

The server provides the following MCP tools:

create_note

Create a new note with title, content, and optional category.

Parameters:

• title (string): The title of the note
• content (string): The content/body of the note
• category (string, optional): The category to organize the note (default: "general")

list_notes

List all notes, optionally filtered by category.

Parameters:

• category (string, optional): Category to filter notes by

read_note

Read the content of a specific note.

Parameters:

• title (string): The title of the note to read
• category (string, optional): The category the note is in (default: "general")

update_note

Update an existing note with new content.

Parameters:

• title (string): The title of the note to update
• content (string): The new content for the note
• category (string, optional): The category the note is in (default: "general")

delete_note

Delete a specific note.

Parameters:

• title (string): The title of the note to delete
• category (string, optional): The category the note is in (default: "general")

search_notes

Search for notes containing the given query text.

Parameters:

• query (string): The text to search for in note titles and content
• category (string, optional): Optional category to limit search to

Configuration

The server uses the following environment variables:

• NOTES_DIR: Directory where notes are stored (default: "notes" in current directory)

File Structure

Notes are stored as Markdown files in the following structure:

notes/
├── general/
│   ├── my_first_note.md
│   └── another_note.md
├── work/
│   └── meeting_notes.md
└── personal/
    └── ideas.md

Development

Running Tests

uv run pytest

Project Structure

notes-mcp/
├── src/
│   └── notes_mcp/
│       ├── __init__.py
│       └── server.py
├── tests/
├── pyproject.toml
└── README.md

License

This project is open source and available under the MIT License.