notion-mpm
Python MCP server + API library for Notion workspace integration.
Provides:
- Clean Python API:
from notion_mpm.api import pages; await pages.get_page(token, page_id) - MCP server: wraps the API for Claude Desktop (
uv run notion-mpm mcp) - 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
