Notion MCP

🚀 Notion MCP Server

A Model Context Protocol (MCP) server implementation for Notion integration, offering standardized interfaces to interact with Notion's API. Compatible with Claude Desktop and other MCP clients.

✨ Features

• List and query Notion databases.
• Create and update pages.
• Search within Notion workspaces.
• Retrieve database details and their child blocks.
• Fully support asynchronous/await functionality (using httpx).
• Implement type safety with Pydantic v2 models.
• Provide error handling with detailed logging.
• Be compatible with MCP 1.6.0.

📦 Installation

1. Clone the repository:

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

2. 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, use the standard venv:

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

3. Create a .env file in the project root directory:

NOTION_API_KEY=your_notion_integration_token

💻 Usage Examples

Basic Usage

1. Test the server (it should run without errors):

python -m notion_mcp

2. 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"
    }
  }
}

Please replace /Users/username/ with your actual user directory path.

📚 Documentation

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:

1. Visit https://www.notion.so/my-integrations.
2. Create a new integration (with appropriate read/write permissions).
3. Copy the generated token and add it to the .env file:

NOTION_API_KEY=your_api_key_here

Contribution Guidelines

To contribute to the project, follow these steps:

1. Fork the project repository.
2. Create a new branch for your feature or fix.
3. Commit your changes and push the branch.
4. Create a pull request to merge into the main branch.

Please ensure that all tests are run before submitting code, and maintain high code quality and clear documentation.

📄 License

This project is licensed under the MIT License.

🔧 Troubleshooting

Common Issues

• Unable to install dependencies: Check your internet connection or try using a different Python version.
• Server fails to start: Ensure that you have correctly configured the API key in the .env file and all dependencies are installed correctly.
• Incompatible with Claude: Check the paths and commands in claude_desktop_config.json.

Contact

If you have any questions or feedback, please submit them via GitHub Issues.