notion-mpm

Python MCP server + API library for Notion workspace integration.

Provides:

1. Clean Python API: from notion_mpm.api import pages; await pages.get_page(token, page_id)
2. MCP server: wraps the API for Claude Desktop (uv run notion-mpm mcp)
3. 20+ tools: pages, blocks, databases, users, search, comments

Setup

cp .env.local.example .env.local
# Add NOTION_API_KEY=secret_...
uv sync

Create a Notion integration at: https://www.notion.so/my-integrations

Then share your pages/databases with the integration inside Notion.

Run

uv run notion-mpm setup    # verify token + workspace
uv run notion-mpm doctor   # health check
uv run notion-mpm mcp      # start MCP server (for Claude Desktop)

Test

uv run pytest
uv run pytest --cov=src --cov-report=html

Claude Desktop Config

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

{
  "mcpServers": {
    "notion": {
      "command": "uv",
      "args": ["run", "--directory", "/path/to/notion-mpm", "notion-mpm", "mcp"]
    }
  }
}

API Overview

src/notion_mpm/
├── api/
│   ├── _client.py      # Shared httpx client + NotionAPIError
│   ├── pages.py        # get, create, update, archive, restore pages
│   ├── blocks.py       # get, append, update, delete blocks + helpers
│   ├── databases.py    # get, create, update, query databases
│   ├── users.py        # list, get, get_bot_user
│   ├── search.py       # search pages and databases
│   └── comments.py     # get and create comments
├── auth/               # Token management from .env/.env.local
├── cli/                # Click CLI commands
└── server/             # Thin MCP adapter over api/

MCP Tools

Category	Tools
Pages	get_page, get_page_property, create_page, update_page, archive_page, restore_page
Blocks	get_block, get_block_children, append_block_children, update_block, delete_block
Databases	get_database, create_database, update_database, query_database
Users	list_users, get_user, get_bot_user
Search	search
Comments	get_comments, create_comment

Token Scopes

Your integration needs these capabilities (set in Notion integration settings):

• Read content — required for all read operations
• Update content — required for create/update/archive
• Insert comments — required for create_comment
• Read comments — required for get_comments

Release

make publish        # patch bump + PyPI + GitHub Release
make publish-minor  # minor bump
make publish-major  # major bump