📌Overview

Purpose: The Notion MCP Server facilitates seamless integration with Notion's API by providing a standardized interface for developers.

Overview: This server implementation of the Model Context Protocol (MCP) allows users to easily connect and interact with various functionalities available within Notion, supporting tasks such as querying databases and managing pages in real-time.

Key Features:

Database Management: Enables users to list, query, and manage Notion databases efficiently, enhancing productivity by allowing streamlined data operations.
Page Operations: Supports the creation and updating of pages, ensuring that users can dynamically interact with their content as needed.
Workspace Search: Facilitates quick searching across the Notion workspace, making it easier to find specific information swiftly.
Asynchronous Support: Full async/await functionality is provided, improving performance by allowing non-blocking operations.
Type Safety: Utilizes Pydantic models for type safety, ensuring robust code quality and reducing errors during development.
Error Handling: Incorporates proper error handling mechanisms to enhance the reliability of interactions with the Notion API.

Notion MCP Server

A Model Context Protocol (MCP) server implementation for Notion integration, providing a standardized interface for interacting with Notion's API. Compatible with Claude Desktop and other MCP clients.

Features

List and query Notion databases
Create and update pages
Search across Notion workspace
Get database details and block children
Full async/await support with httpx
Type-safe with Pydantic v2 models
Proper error handling with detailed logging
Compatibility with MCP 1.6.0

Installation

Clone the repository:

git clone https://github.com/ccabanillas/notion-mcp.git
cd notion-mcp

Create a virtual environment and install dependencies (using uv):

uv venv
source .venv/bin/activate  # On Windows: .venv\Scripts\activate
uv pip install -e .

Alternatively, using standard venv:

python -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate
pip install -e .

Create a .env file in the project root:

NOTION_API_KEY=your_notion_integration_token

Usage

Test the server (it should run without errors):
```
python -m notion_mcp
```

To use it with Claude Desktop, adjust your claude_desktop_config.json file (located at ~/Library/Application Support/Claude/claude_desktop_config.json on macOS):

{
  "servers": {
    "notion-mcp": {
      "command": "/Users/username/Projects/notion-mcp/.venv/bin/python",
      "args": ["-m", "notion_mcp"],
      "cwd": "/Users/username/Projects/notion-mcp"
    }
  }
}

Be sure to replace /Users/username/ with your actual home directory path.

Development

Project Structure

notion-mcp/
├── src/
│   └── notion_mcp/
│       ├── models/
│       │   ├── __init__.py
│       │   └── notion.py      # Pydantic models for Notion objects
│       ├── __init__.py        
│       ├── __main__.py        # Entry point
│       ├── client.py          # Notion API client
│       └── server.py          # MCP server implementation
├── .env                       # Environment variables (add your Notion API key here)
├── .gitignore
├── pyproject.toml             # Project dependencies
└── README.md

Running Tests

pytest

Configuration

The server requires a Notion integration token. To set this up:

Go to https://www.notion.so/my-integrations
Create a new integration with appropriate capabilities (read/write as needed)
Copy the integration token
Add it to your .env file in the project root directory:
```
NOTION_API_KEY=your_notion_integration_token
```
Share your Notion databases with the integration (from the database's "Share" menu)

Contributing

Fork the repository
Create your feature branch (git checkout -b feature/amazing-feature)
Commit your changes (git commit -m 'Add some amazing feature')
Push to the branch (git push origin feature/amazing-feature)
Open a Pull Request

License

MIT License - Use at your own risk

Troubleshooting

Common Issues

Connection Errors: Make sure your Notion API key is correct and you have internet access
Permission Errors: Ensure your integration has been given access to the databases you're trying to access
Claude Desktop Integration: If Claude Desktop isn't connecting, check that your config path is correct and that the server is running without logging to stdout

Acknowledgments

Built to work with Claude Desktop and other MCP clients
Uses Notion's API (latest compatible version 2022-02-22)
MCP 1.6.0 compatibility maintained
Special thanks to danhilsé, referencing his notion-mcp-server project