Notion MCP Server

Notion MCP Server

Version 0.1.0

Stateless MCP server exposing the full Notion API as 33 tools over streamable-http transport. No server-side secrets — each user passes their own Notion integration token via Authorization header.

Prerequisites

• Notion Integration Token — required for every user who connects
• Docker (for deployment) or Python 3.13+ with uv (for local development)

Notion Integration Setup

Every user needs their own Notion integration token. Create one per user:

1. Go to https://www.notion.so/profile/integrations
2. Click "New integration"
3. Give it a name (e.g., "MCP - John")
4. Select the workspace
5. Click Submit — you'll get a token starting with ntn_
6. Share pages with the integration: open each page/database in Notion, click the ... menu → Connections → Add connection → select your integration name

The integration only has access to pages explicitly shared with it. Without sharing, search_pages returns nothing.

Deploy with Docker

git clone https://github.com/LRGEX/notion-mcp.git
cd notion-mcp
docker compose build
docker compose up -d

Server starts on port 9201. Verify it's running:

curl -X POST http://localhost:9201/mcp \
  -H "Content-Type: application/json" \
  -H "Accept: application/json" \
  -d '{"jsonrpc":"2.0","method":"initialize","params":{"protocolVersion":"2025-03-26","capabilities":{},"clientInfo":{"name":"test","version":"1.0"}},"id":1}'

Expected response: JSON with "result" containing server capabilities.

Connect an MCP Client

Oh My Pi

Add to ~/.omp/agent/mcp.json or .omp/mcp.json:

{
  "$schema": "https://raw.githubusercontent.com/can1357/oh-my-pi/main/packages/coding-agent/src/config/mcp-schema.json",
  "mcpServers": {
    "notion": {
      "type": "http",
      "url": "http://YOUR_SERVER_IP:9201/mcp",
      "headers": {
        "Authorization": "Bearer ntn_your_integration_token_here",
        "Accept": "application/json, text/event-stream"
      }
    }
  }
}

Replace YOUR_SERVER_IP with the server address (e.g., 192.168.1.101).Replace ntn_your_integration_token_here with your actual ntn_ token from the integration setup above.

Claude Desktop / Other MCP Clients

For any MCP client that supports streamable-http transport, point it at:

• Endpoint: http://YOUR_SERVER_IP:9201/mcp

Pass the token in the Authorization: Bearer ntn_xxx header.

Multi-User

Multiple users can connect to the same server simultaneously. Each user provides their own ntn_ token in the Authorization header. The server is fully stateless — no sessions, no stored tokens, no .env file.

10 users = 10 different tokens, same Docker container, same port.

Run Locally (without Docker)

Requires Python 3.13+ and uv:

git clone https://github.com/LRGEX/notion-mcp.git
cd notion-mcp
uv sync
uv run notion-mcp

Server starts on http://0.0.0.0:9201.

Tools (33)

All tools automatically use the token from the request's Authorization header. No token parameter is needed in any tool call.

Meta

Search

Pages

Data Sources (Databases)

Databases

Blocks

Comments

Users

File Uploads

Architecture

• Stateless — no stored tokens, no sessions, no .env file
• Auth via header — reads Authorization: Bearer ntn_xxx from every request
• Multi-user — different tokens per connection, zero shared state
• Transport — streamable-http
• Framework — FastMCP from the official mcp Python SDK
• API client — notion-client v3.1.0 (official Notion async client)

Port Allocation

Project Structure

notion_mcp/
├── Dockerfile
├── docker-compose.yml
├── pyproject.toml
├── README.md
├── src/notion_mcp/
│   ├── __init__.py            # Package metadata
│   ├── client.py              # create_client(token) — stateless factory
│   ├── server.py              # FastMCP server — all 33 tool definitions
│   └── tools/                 # (unused — tools are inline in server.py)
│       ├── blocks.py
│       ├── comments.py
│       ├── data_sources.py
│       ├── databases.py
│       ├── files.py
│       ├── pages.py
│       ├── search.py
│       └── users.py
└── mcp_configs/
    └── notion.json            # MCP client config reference

Dependencies

License

Proprietary — LRGEX. All rights reserved.