fastmcp-notes

A FastMCP v3 feature showcase: a note-taking knowledge base exposed as an MCP server.

Features demonstrated

• Tools -- CRUD operations on notes with tag categorization
• Resources -- note listing (static URI) and note detail (URI template)
• Prompts -- parameterized templates for note analysis and brainstorming
• Context -- structured logging (ctx.info), progress reporting (ctx.report_progress), and cross-resource reads (ctx.read_resource)
• Lifespan -- server startup/shutdown lifecycle with shared state
• Error handling -- ToolError for domain-specific errors

Setup

git clone <repo-url>
cd fastmcp-notes
uv sync

Usage

Run the server (stdio, for Claude Desktop)

fastmcp run server.py

Run the server (HTTP, for the client demo)

fastmcp run server.py -t streamable-http -p 8000

Run the client demo

# In another terminal, with the server running on port 8000:
python client.py

Claude Desktop configuration

Add to ~/Library/Application Support/Claude/claude_desktop_config.json:

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

Screenshots

Creating a note via Claude Desktop

Creating a note

Prompts and resources available from the + menu

Prompts and resources

Reading a note by title

Reading a note

Project structure

server.py    # MCP server -- tools, resources, prompts, lifespan, error handling
client.py    # Async client demo

License

MIT