forgejo_admin
Repositories
58
 Projects Packages
18
 Public activity Starred repositories

notion-mcp-ldraney (0.1.13)

Published 2026-03-01 18:22:25 +00:00 by forgejo_admin

Installation

pip install --index-url  notion-mcp-ldraney

About this package

MCP server wrapping the Notion Python SDK (v2025-09-03)

PyPI License: MIT Python 3.10+

notion-mcp

MCP (Model Context Protocol) server that wraps ldraney/notion-sdk — a Python SDK for the Notion API v2025-09-03.

Overview

This project exposes the full Notion Python SDK as MCP tools, allowing AI assistants (Claude, etc.) to interact with Notion workspaces through a standardized tool interface.

Why this over the official Notion MCP servers?

The problem

There are two official Notion MCP implementations:

  1. Open-source makenotion/notion-mcp-server (TypeScript) — issues and PRs "not actively monitored," may be sunset in the future
  2. Closed-source hosted MCP at mcp.notion.com — what Claude Desktop's "Connections > Notion" uses

Neither works reliably. This is well-documented in issues like #142 ("Two Notion MCP servers, neither work well"). The open-source server was abandoned for 3.5 months after the v2025-09-03 breaking API change, shipped a broken v2.0.0 (Dec 2025), and still has open showstopper bugs in v2.1.0.

Comparison

Official open-source Official hosted notion-mcp-ldraney
Status "Not actively monitored" Closed-source Actively maintained
Language TypeScript N/A Python
API version 2025-09-03 (broken) Unknown 2025-09-03 (working)
Auth Bearer token (version header trap) OAuth only Bearer token (correct headers always)
Serialization Double-stringifies nested objects (#196) N/A Accepts both JSON strings and raw objects
Property updates Blocked by additionalProperties: false (#184) Unknown Works correctly
Database queries retrieve-a-database was missing for 5 weeks Some tools gated to Enterprise query_database auto-resolves data sources
Tool count 22 ~10 26
Context cost ~8k+ tokens (est.) ~21k tokens (measured) ~8.6k tokens (measured)
Convenience tools None Limited archive_page, archive_database, query_database
Install npm Claude Desktop only PyPI (uvx), .mcpb (planned)

Key advantages

  • 2.5x more token-efficient — 26 tools in ~8.6k tokens vs the official Claude-managed Notion integration's 12 tools in ~21.4k tokens. Less context overhead means more room for actual conversation
  • Correct API headers always — Built on notion-sdk-ldraney, which always sends the Notion-Version: 2025-09-03 header correctly
  • LLM-friendly parameter handling — str | dict union types so tools don't break when LLMs pass raw objects instead of JSON strings
  • Convenience tools — Operations like archive_page, archive_database, and query_database (with auto data-source resolution) reduce multi-step workflows to single calls
  • Works everywhere — uvx, pip, Claude Code, any MCP-compatible client

SDK Coverage

Every method in notion-sdk maps to an MCP tool, organized by module:

Pages

Tool SDK Method Notion Endpoint
create_page create_page() POST /v1/pages
get_page get_page() GET /v1/pages/{id}
update_page update_page() PATCH /v1/pages/{id}
archive_page archive_page() PATCH /v1/pages/{id}
move_page move_page() POST /v1/pages/{id}/move

Databases

Tool SDK Method Notion Endpoint
create_database create_database() POST /v1/databases
get_database get_database() GET /v1/databases/{id}
update_database update_database() PATCH /v1/databases/{id}
archive_database archive_database() PATCH /v1/databases/{id}
query_database query_database() auto-resolves data source, then POST /v1/data_sources/{id}/query

Data Sources

Tool SDK Method Notion Endpoint
get_data_source get_data_source() GET /v1/data_sources/{id}
update_data_source update_data_source() PATCH /v1/data_sources/{id}
query_data_source query_data_source() POST /v1/data_sources/{id}/query
list_data_source_templates list_data_source_templates() GET /v1/data_sources/{id}/templates

Blocks

Tool SDK Method Notion Endpoint
get_block get_block() GET /v1/blocks/{id}
get_block_children get_block_children() GET /v1/blocks/{id}/children
append_block_children append_block_children() PATCH /v1/blocks/{id}/children
update_block update_block() PATCH /v1/blocks/{id}
delete_block delete_block() DELETE /v1/blocks/{id}

Users

Tool SDK Method Notion Endpoint
get_users get_users() GET /v1/users
get_self get_self() GET /v1/users/me

Comments

Tool SDK Method Notion Endpoint
create_comment create_comment() POST /v1/comments
get_comments get_comments() GET /v1/comments

Search

Tool SDK Method Notion Endpoint
search search() POST /v1/search

26 tools total covering the complete Notion API v2025-09-03 surface.

Architecture

notion-mcp/
├── src/
│   └── notion_mcp/
│       ├── server.py          # MCP server entry point
│       ├── tools/
│       │   ├── pages.py       # Page tools
│       │   ├── databases.py   # Database & data source tools
│       │   ├── blocks.py      # Block tools
│       │   ├── users.py       # User tools
│       │   ├── comments.py    # Comment tools
│       │   └── search.py      # Search tools
│       └── ...
├── tests/
├── pyproject.toml
└── README.md

Each tool module mirrors the SDK's mixin structure, keeping a clean 1:1 mapping.

Prerequisites

  • Python >= 3.10
  • A Notion integration API key (NOTION_API_KEY)
  • notion-sdk (installed as a dependency)

Setup

# Clone and install
git clone https://github.com/ldraney/notion-mcp.git
cd notion-mcp
uv sync  # or: pip install -e .

# Set your API key
export NOTION_API_KEY="ntn_..."

Usage

With Claude Code

The repo ships with a .mcp.json that configures everything automatically. Just cd into the project and start Claude Code — it picks up the config and reads NOTION_API_KEY from your environment. The ${NOTION_API_KEY} syntax in .mcp.json tells Claude Code to interpolate the value from your shell environment at server startup, so your API key is never hardcoded in config files.

To use notion-mcp from other projects, add this to that project's .mcp.json:

{
  "mcpServers": {
    "notion": {
      "command": "uv",
      "args": ["run", "--directory", "/path/to/notion-mcp", "python", "-m", "notion_mcp"],
      "env": {
        "NOTION_API_KEY": "${NOTION_API_KEY}"
      }
    }
  }
}

Or add it to ~/.mcp.json to make it available globally across all projects.

See hello-mcp for more on the ${VAR} env secret pattern.

With uvx

uvx notion-mcp-ldraney

Standalone

python -m notion_mcp

Related

Requirements

Requires Python: >=3.10
Details
PyPI
2026-03-01 18:22:25 +00:00
2
Lucas Draney
MIT
43 KiB
Assets (2)
notion_mcp_ldraney-0.1.13-py3-none-any.whl 17 KiB
notion_mcp_ldraney-0.1.13.tar.gz 26 KiB
Versions (1) View all
0.1.13 2026-03-01