使用说明
Notes MCP Server
A sample MCP (Model Context Protocol) server that manages notes in SQLite, built with FastMCP 4. Companion repo for three blog posts:
- Part 1: How to Build an MCP Server in Python (Step-by-Step) — the local STDIO server.
- Part 2: How to Deploy a Python MCP Server: Remote HTTP, Auth, and Docker — taking it remote.
- Part 3: How to Test and Debug a Python MCP Server — the Inspector, in-process pytest, and the stdio traps that silently break a passing server.
Setup
python -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt
Usage
Local (STDIO)
python server.py
This initializes the SQLite database and starts the MCP server over STDIO, the transport Claude Desktop and most IDE clients spawn locally.
Remote (HTTP + auth)
Set a bearer token and run over HTTP:
MCP_TOKEN="your-secret-token" MCP_TRANSPORT=http python server.py
The server listens on http://0.0.0.0:8000/mcp. Clients must send Authorization: Bearer your-secret-token. Without MCP_TOKEN, no auth gate is applied (fine for local STDIO, not for a public server).
| Env var | Default | Purpose |
|---|---|---|
MCP_TOKEN |
unset | Bearer token; enables the auth gate when set |
MCP_TRANSPORT |
stdio |
Set to http to serve remotely |
HOST |
0.0.0.0 |
HTTP bind host |
PORT |
8000 |
HTTP bind port |
StaticTokenVerifierstores tokens in plaintext and is meant for development or a single-user server behind a VPN. For a public, multi-tenant server, swapbuild_auth()forJWTVerifieror OAuth 2.1 — the tools do not change.
Docker
docker build -t notes-mcp .
docker run -d -p 8000:8000 -e MCP_TOKEN="your-secret-token" --name notes-mcp notes-mcp
Run it behind a reverse proxy that terminates TLS (set proxy_buffering off and a generous proxy_read_timeout for the streaming endpoint). For horizontal scaling, run the ASGI app under a process manager: uvicorn server:app --host 0.0.0.0 --port 8000 (create_app() wires init_db() into the startup lifespan).
MCP Surface Area
| Type | Name | Description |
|---|---|---|
| Tool | add_note |
Create a new note |
| Tool | search_notes |
Search notes by title or content |
| Tool | delete_note |
Delete a note by ID |
| Resource | note://{note_id} |
Read a single note |
| Resource | note://all |
List all notes |
| Prompt | summarize_notes |
Summarize all notes (brief or detailed) |
Tests
pytest
