Notion Memory MCP 🧠

A Model Context Protocol server that turns Notion into a programmable memory tier for AI agents.

Give any MCP-compatible agent (Hermes, Claude Desktop, Cursor, custom agents) five clean tools to search, read, save, append, and query your Notion workspace — making Notion the persistent "disk" layer of an agent's 3-tier memory architecture.

⚡ L1 cache  → agent built-in memory (always in context)
🧮 RAM       → mem0 / vector store (auto recall)
💾 DISK      → Notion via this MCP ← you are here

Why

Agent memory solutions (mem0, honcho...) are opaque — great for reflexive recall, invisible to humans. Notion is the opposite: fully visible and editable by humans, but not natively tool-callable.

This server bridges them: agents get programmatic access; humans keep full visual control.

Tools exposed

Tool	What it does
notion_search(query)	Find pages/databases by title or content
notion_read(page_id)	Read a page as structured plain text
notion_save(title, content)	Upsert page by exact title (markdown-ish → blocks)
notion_append(page_id, text)	Append to a page (running logs)
notion_query_db(db_id)	Query database rows with optional select-filter

Setup

pip install -r requirements.txt
export NOTION_API_TOKEN=ntn_your_integration_token   # notion.so/my-integrations
python3 server.py                                     # stdio transport

Hermes Agent

hermes mcp add notion-memory -- python3 /path/to/server.py
# with env: NOTION_API_TOKEN set in ~/.hermes/.env

Claude Desktop / Cursor

Add to your MCP config:

{
  "mcpServers": {
    "notion-memory": {
      "command": "python3",
      "args": ["/path/to/server.py"],
      "env": { "NOTION_API_TOKEN": "ntn_..." }
    }
  }
}

Design decisions

• Upsert-by-title (notion_save): agents think in names, not UUIDs. Re-saving replaces the body — idempotent writes.
• Markdown-ish → blocks: headings (#), bullets (-), paragraphs map to native Notion blocks. No complex AST.
• Read-open, write-scoped: reads hit whatever the integration can see; create/update only. No delete tool by design — destructive ops stay human-only.
• stdlib + httpx + mcp: minimal dependencies, easy audit.

Skills demonstrated

MCP server development · async Python (httpx + asyncio) · Notion API (search/blocks/databases) · protocol design for LLM tool use · defensive API error mapping

License

MIT — built by Shahjalal Shanto

Part of an agent-memory architecture: built-in cache + mem0 RAM + Notion disk.