mcp-server-demo

A minimal Model Context Protocol server that gives an LLM a persistent scratchpad. It exists to demonstrate all three MCP primitives — tools, resources, and prompts — in about 80 lines of Python.

Built against the Python SDK v2 (mcp>=2.1.1), where FastMCP was renamed to MCPServer.

What it exposes

The tool/resource split is the point worth noticing. read_notes is a tool because the model decides when to call it. notes://latest is a resource because the client decides when to attach it — it's context, not an action.

Related MCP server: flomo-mcp

Install

Requires Python 3.12+ and uv.

git clone https://github.com/DinaMMahfouz/mcp-server-demo.git
cd mcp-server-demo
uv sync

Verify it imports cleanly:

uv run python -c "import mcp_server_demo.main; print('ok')"

Run

uv run mcp-server-demo

The process will appear to hang. That is correct — it speaks JSON-RPC over stdio and is waiting for a client. Ctrl+C to exit.

To poke at it interactively:

uv run mcp dev src/mcp_server_demo/main.py

Connect to Claude Desktop

Edit claude_desktop_config.json:

• Windows — %APPDATA%\Claude\claude_desktop_config.json

• macOS — ~/Library/Application Support/Claude/claude_desktop_config.json

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

The path must be absolute. Restart Claude Desktop; the tools appear in the tools menu.

Storage

Notes are written to a per-user data directory, not into the package:

• Windows — %LOCALAPPDATA%\mcp-server-demo\notes.txt

• Linux/macOS — $XDG_DATA_HOME/mcp-server-demo/notes.txt, falling back to ~/.local/share/

Override with the STICKY_NOTES_FILE environment variable.

Scope

This is a learning project. It has no tests, no concurrency handling, and no input validation beyond stripping whitespace — a plain-text file appended to by one process. Don't build on it.

License

MIT.