Skip to main content
Glama
Sign In
notion-mpm

notion-mpm

by bobmatnyc
OverviewSchemaSourceRelated ServersDiscussionsAdmin
Python
Remote

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.

Related MCP server: @node2flow/notion-mcp

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

Available Tools

21 tools
append_block_childrenA

Append new content blocks to a page or block. Use this to add paragraphs, headings, lists, code blocks, and more.

Inputs: block_id (required), children (required), after.

archive_pageA

Archive (soft-delete) a Notion page. The page can be restored later.

Inputs: page_id (required).

create_commentB

Add a comment to a Notion page. Requires 'insert comments' capability on the integration.

Inputs: text (required), page_id, discussion_id.

create_databaseA

Create a new Notion database as a child of an existing page. Define the property schema (columns) at creation time.

Inputs: title (required), properties (required), parent_page_id (required), is_inline.

create_pageA

Create a new Notion page inside a database or as a sub-page of another page. For database pages, properties must match the database schema.

Inputs: parent (required), properties (required), icon, cover, +1 more.

delete_blockB

Delete a block from a Notion page.

Inputs: block_id (required).

get_blockB

Retrieve a specific block by its ID.

Inputs: block_id (required).

get_block_childrenA

List the direct children of a block or page. Use this to read the content of a Notion page.

Inputs: block_id (required), page_size, start_cursor.

get_bot_userA

Retrieve information about the bot user associated with this integration, including workspace name and owner details.

Inputs: no named parameters.

get_commentsA

Retrieve all comments on a Notion page or block.

Inputs: block_id (required), page_size, start_cursor.

get_databaseA

Retrieve a Notion database schema and metadata by its ID.

Inputs: database_id (required).

get_pageA

Retrieve a Notion page by its ID, including all properties.

Inputs: page_id (required).

get_page_propertyB

Retrieve a specific property value from a Notion page.

Inputs: page_id (required), property_id (required), page_size.

get_userA

Retrieve information about a specific Notion user.

Inputs: user_id (required).

list_usersB

List all users in the Notion workspace.

Inputs: page_size, start_cursor.

query_databaseB

Query a Notion database to retrieve pages matching filter criteria. Supports filtering, sorting, and pagination.

Inputs: database_id (required), sorts, filter, page_size, +1 more.

restore_pageA

Restore a previously archived Notion page.

Inputs: page_id (required).

searchB

Search for pages and databases in the Notion workspace. Only returns content the integration has access to.

Inputs: query, page_size, filter_type, start_cursor, +1 more.

update_blockC

Update the content of an existing block.

Inputs: block_id (required), block_data (required).

update_databaseA

Update a Notion database title, description, or property schema.

Inputs: database_id (required), title, properties, description.

update_pageB

Update a Notion page's properties, icon, or cover image.

Inputs: page_id (required), icon, cover, properties.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    Deploy Server
    One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

    TDQS

    A3.7/5.0

    Scored across 21 tools

    Disambiguation5/5

    Each tool maps to a distinct Notion resource and action. get_page_property targets a specific property vs get_page's full page, and append_block_children vs get_block_children are clearly read vs write. No two tools have overlapping purposes.

    Naming Consistency5/5

    All tools follow a verb_noun pattern with snake_case, e.g., get_page, create_database, update_block. The only deviation is 'search', but it is a clear imperative verb that fits the style. No mixed conventions.

    Tool Count4/5

    21 tools is above the typical 3-15 sweet spot, but the breadth of Notion's API (pages, blocks, databases, users, comments) justifies the count. Each tool serves a specific operation, so it doesn't feel bloated.

    Completeness4/5

    Core CRUD and lifecycle operations are covered for pages, blocks, and databases, plus search, comments, and user retrieval. A notable minor gap is lack of database archive/restore operations, but this does not severely hinder common workflows.

    Maintenance

    ActivityInactive
    ResponsivenessOutdated data

    Resources

    Related MCP Connectors

    Related MCP Servers