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

Key advantages

• Correct API headers always — Built on ldraney-notion-sdk, 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

Databases

Data Sources

Blocks

Users

Comments

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
git clone https://github.com/ldraney/notion-mcp.git
cd notion-mcp

# Install
pip install -e .

# Configure
export NOTION_API_KEY="ntn_..."

Usage

With Claude Code

Add to your Claude Code MCP config (~/.claude/settings.json or project settings):

{
  "mcpServers": {
    "notion": {
      "command": "python",
      "args": ["-m", "notion_mcp"],
      "env": {
        "NOTION_API_KEY": "ntn_..."
      }
    }
  }
}

Standalone

python -m notion_mcp

Related

• ldraney/notion-sdk — The underlying Python SDK this server wraps