notes-mcp

A note-taking MCP server. Notes are dated, and the same process also exposes a plain REST API and an HTML view — so it can run locally as a stdio MCP server, or be hosted as a normal web service.

Storage

SQLite by default (NOTES_DB_PATH, defaults to ./data/notes.db) — fine for local/stdio use and for hosts with a persistent disk.

Set DATABASE_URL to a Postgres connection string instead, and the server switches to Postgres automatically — needed on platforms with no persistent disk for the app container itself (e.g. Render's free web services, see below). Same schema, same behavior, just a different backend.

MCP tools

• add_note(content, date?) — add a note; date defaults to today (YYYY-MM-DD)
• delete_note(note_id) — delete a note by id
• get_notes_for_date(date?) — notes for a given date, defaults to today
• list_all_notes() — every note, most recent date first
• view_notes_html(date?) — returns an HTML page of all notes, grouped by date, with the given/today's date highlighted

Auth (HTTP mode)

When running with MCP_TRANSPORT=http, every request — the REST API and the /mcp endpoint alike — requires Authorization: Bearer <NOTES_API_TOKEN>. /healthz is the only unauthenticated route (for container health checks). The server refuses to start over HTTP if NOTES_API_TOKEN isn't set.

Generate a token and keep it secret, e.g.:

python -c "import secrets; print(secrets.token_urlsafe(32))"

Stdio mode (local Claude Desktop/Code) has no auth — the client already trusts it by spawning the process directly, and there's no network exposure.

REST API

Available when running with MCP_TRANSPORT=http (always on in the Docker image). All requests below need the Authorization: Bearer <token> header.

Method	Path	Body / Query	Description
POST	/api/notes	{"content", "date"?}	Create a note
GET	/api/notes	?date=YYYY-MM-DD	List all notes, or by date
GET	/api/notes/today	—	Today's notes
GET	/api/notes/{id}	—	Get one note
DELETE	/api/notes/{id}	—	Delete a note
GET	/notes	?date=YYYY-MM-DD	HTML view (highlights that date)
GET	/healthz	—	Health check

The MCP endpoint (streamable-http) is mounted at /mcp on the same port.

Local setup (stdio, for Claude Desktop/Code)

python -m venv .venv
.venv\Scripts\pip install -r requirements.txt
.venv\Scripts\python server.py

Register with Claude Code

claude mcp add notes -- "C:\Users\srjnm\git\notes-mcp\.venv\Scripts\python.exe" "C:\Users\srjnm\git\notes-mcp\server.py"

Register with Claude Desktop

Add to claude_desktop_config.json:

{
  "mcpServers": {
    "notes": {
      "command": "C:\\Users\\srjnm\\git\\notes-mcp\\.venv\\Scripts\\python.exe",
      "args": ["C:\\Users\\srjnm\\git\\notes-mcp\\server.py"]
    }
  }
}

Run locally over HTTP (MCP + REST, no Docker)

NOTES_API_TOKEN=devtoken MCP_TRANSPORT=http PORT=8000 .venv\Scripts\python server.py

Docker (hosted deployment)

docker build -t notes-mcp .
docker run -d --name notes-mcp -p 8000:8000 \
  -e NOTES_API_TOKEN=<your-token> \
  -v notes-data:/data \
  notes-mcp

The notes-data named volume keeps notes.db across container restarts and upgrades. Point an MCP client at http://<host>:8000/mcp (streamable-http) with an Authorization: Bearer <your-token> header, or call the REST API directly at http://<host>:8000/api/notes with the same header.

Claude Code, as a remote MCP client:

claude mcp add --transport http notes http://<host>:8000/mcp \
  --header "Authorization: Bearer <your-token>"

Deploying to Render

Render's free web services have no persistent disk, so this repo talks to Postgres there instead of the local SQLite file.

1. Push this repo to GitHub (Render deploys from a git repo).
2. Create a Postgres database in the Render dashboard (New → PostgreSQL). Free instances expire after 30 days — fine to start with, upgrade to a paid instance whenever you want the data to stick around longer.
3. Create a Web Service from the same repo (New → Web Service → pick this repo). Render detects the Dockerfile automatically.
4. Set env vars on the web service (Environment tab):
   • DATABASE_URL → copy the Postgres instance's Internal Database URL from its dashboard page and paste it here.
   • NOTES_API_TOKEN → your generated token.
   • Leave PORT unset — Render injects its own and the app already reads PORT from the environment.
5. Deploy. Render terminates HTTPS for you at https://<your-service>.onrender.com, so there's no Caddy/reverse-proxy step needed (unlike a bare VPS).

Then point clients at https://<your-service>.onrender.com/mcp (MCP) or .../api/notes (REST), both with the Authorization: Bearer <token> header.