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

• 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

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 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

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