File Notes MCP Server

A beginner-level MCP (Model Context Protocol) server built with Python and FastMCP. It lets any MCP-compatible client create, list, read, search and delete plain-text notes. Notes are stored as .txt files in a local notes/ folder.

Features

• Five MCP tools for managing notes

• Notes stored as plain .txt files (no database)

• Title validation to block empty names, path traversal (../) and unsupported characters

• Clear error messages; errors never crash the server

Related MCP server: sample-notes-mcp-server

Tech Stack

Project Structure

file-notes-mcp/
├── server.py          # MCP server (entry point)
├── requirements.txt   # Dependencies
├── notes/             # Stored notes (sample data only)
├── screenshots/       # Demo screenshots
└── README.md

Installation

1. Clone the repository and enter the folder:

   git clone <your-repo-url>
   cd file-notes-mcp

2. (Optional, recommended) Create and activate a virtual environment:

   # Windows
   python -m venv .venv
   .venv\Scripts\activate
   
   # macOS / Linux
   python3 -m venv .venv
   source .venv/bin/activate

3. Install dependencies:

   pip install -r requirements.txt

Starting the Server

python server.py

The server uses the STDIO transport, so it is normally launched by a client rather than used directly in the terminal.

Connecting with MCP Inspector

1. Run:

   mcp dev server.py

   (Alternative: npx @modelcontextprotocol/inspector python server.py. This needs Node.js.)

2. Open the local URL printed in the terminal.

3. Set Transport Type to STDIO, Command to python, Arguments to server.py, then click Connect.

4. Open the Tools tab and click List Tools.

Tools

search_notes searches note content.

Example Tool Calls

create_note

{ "title": "MCP Architecture", "content": "The client connects to the server using JSON-RPC." }

Result: Note 'MCP Architecture' created successfully.

list_notes

{}

Result: ["AI", "Internship Assignment", "MCP Architecture"]

read_note

{ "title": "MCP Architecture" }

Result: the content of the note.

search_notes

{ "keyword": "connects" }

Result: ["MCP Architecture"]

delete_note

{ "title": "AI" }

Result: Note 'AI' deleted successfully.

Title Validation Rules

• Titles cannot be empty or only spaces

• Only letters, numbers, spaces, underscores (_) and hyphens (-) are allowed

• Path traversal (../) and slashes are rejected

• The resolved file path must stay inside the notes/ folder

Error Handling

All errors are returned to the client as clear messages and the server keeps running.

Demo Sequence

1. Create two notes

2. List notes

3. Read one note

4. Search by a word from its content

5. Delete one note

6. List notes again

7. Test the error cases: duplicate, unknown and unsafe title

Notes

• The server uses STDIO transport (one client per server process).

• To let multiple clients share one running server, change the last line of server.py to mcp.run(transport="streamable-http").

• The notes/ folder contains sample data only.