README - Notion MCP Server by flyer103

Notion MCP Server

A Model Context Protocol (MCP) server for interacting with Notion APIs.

Overview

This project implements an MCP server that interfaces with Notion's API, allowing AI models to interact with Notion documents and data. It follows the Model Context Protocol specification and uses the official MCP Python SDK.

Requirements

Python 3.12 or higher
uv for package management

Installation

# Clone the repository
git clone https://github.com/flyer103/notion-mcp.git
cd notion-mcp

# Install dependencies using uv
uv venv
source .venv/bin/activate
uv pip install -e ".[dev]"

Configuration

Before using the Notion MCP server, you need to set up a Notion integration and get an API key:

Go to https://www.notion.so/my-integrations
Create a new integration
Set the API key as an environment variable:

export NOTION_API_KEY="your_api_key_here"

Share your Notion content with the integration:
- Open the Notion page you want to access
- Click the "..." menu in the top-right corner
- Select "Add connections"
- Find and select your integration from the list
- The integration now has access to this page and all its subpages

Usage

The Notion MCP server supports two transport methods:

1. Standard Input/Output (stdio)

This is the default mode, used by Claude for Desktop and other MCP-compatible LLM clients:

python -m notion_mcp.server

2. Server-Sent Events (SSE)

For web-based integrations, you can use the SSE transport:

python -m notion_mcp.server --transport sse --host 0.0.0.0 --port 8000

The server will be available at http://localhost:8000/sse

Available Tools

The Notion MCP server provides the following capabilities as tools:

Page Operations

get_page: Get a Notion page by ID
update_page: Update a Notion page's properties
create_page: Create a new Notion page

Database Operations

get_database: Get a Notion database by ID
query_database: Query a Notion database
create_database: Create a new Notion database
update_database: Update a Notion database

Block Operations

get_block: Get a Notion block by ID
update_block: Update a Notion block's content
list_blocks: List a block's children
append_blocks: Append blocks to a block's children
delete_block: Delete a Notion block

Comment Operations

create_comment: Create a new Notion comment
get_comment: Get a Notion comment by ID

Search Operations

search: Search for Notion objects

Command-Line Options

usage: python -m notion_mcp.server [-h] [--port PORT] [--host HOST] [--transport {stdio,sse}] [--debug]

Notion MCP Server

options:
  -h, --help            show this help message and exit
  --port PORT           Port to listen on for SSE transport
  --host HOST           Host to bind the server to
  --transport {stdio,sse}
                        Transport type (stdio or sse)
  --debug               Enable debug mode

Testing with Claude for Desktop

To use this MCP server with Claude for Desktop, you need to create a configuration file:

Create a file called claude_desktop_config.json in the following location:
- macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
- Windows: %APPDATA%\Claude\claude_desktop_config.json
- Linux: ~/.config/Claude/claude_desktop_config.json
Add the following configuration to the file (adjust paths as needed):

{
  "mcpServers": {
    "notion-mcp": {
      "command": "/ABSOLUTE/PATH/TO/YOUR/uv",
      "args": [
        "--directory",
        "/ABSOLUTE/PATH/TO/YOUR/notion-mcp",
        "run",
        "-m",
        "notion_mcp.server"
      ],
      "env": {
        "NOTION_API_KEY": "your_notion_api_key"
      }
    }
  }
}

Replace /ABSOLUTE/PATH/TO/YOUR/uv with the absolute path to your uv executable
Replace /ABSOLUTE/PATH/TO/YOUR/notion-mcp with the absolute path to your notion-mcp installation
Replace your_notion_api_key with your Notion API key (or you can omit the env section if you've set it as a system environment variable)
Save the file and restart Claude for Desktop

You can check Claude's logs for any MCP-related issues:

# Check Claude's logs for errors
tail -n 20 -f ~/Library/Logs/Claude/mcp*.log

Claude will now have access to your Notion MCP server and can interact with Notion documents. You can ask Claude to perform actions like "Create a page in Notion" or "Search my Notion workspace."

Verifying Configuration

To verify that Claude is correctly configured to use your Notion MCP server, you can ask Claude: "Can you list the tools you have access to?" or "Can you create a new page in my Notion workspace?"

If there are any connection issues, check that:

The configuration file is correctly formatted and in the right location
The paths in the configuration are correct
Your Notion integration has the proper permissions

Troubleshooting Common Issues

"spawn uv ENOENT" Error

If you encounter this error:

spawn uv ENOENT {"context":"connection","stack":"Error: spawn uv ENOENT\n at ChildProcess._handle.onexit (node:internal/child_process:285:19)\n at onErrorNT (node:internal/child_process:483:16)\n at process.processTicksAndRejections (node:internal/process/task_queues:82:21)"}

This means Claude Desktop cannot find the uv executable in your PATH. To fix this:

Find the absolute path to your uv executable:

# On macOS/Linux
which uv

# On Windows
where uv

Use the full absolute path in your configuration:

{
  "mcpServers": {
    "notion-mcp": {
      "command": "/ABSOLUTE/PATH/TO/YOUR/uv",
      "args": [
        "--directory",
        "/ABSOLUTE/PATH/TO/YOUR/notion-mcp",
        "run",
        "-m",
        "notion_mcp.server"
      ],
      "env": {
        "NOTION_API_KEY": "your_notion_api_key"
      }
    }
  }
}

Save the file and restart Claude Desktop.

License

This project is licensed under the Apache License 2.0 - see the LICENSE file for details.