Notion

by ccabanillas

96 stars
Not rated
GitHub

About

Integrates Notion's API, enabling workflows to interact with Notion databases and pages for dynamic content management and retrieval.

Details

Author
ccabanillas
Repository
ccabanillas/notion-mcp
GitHub stars
96
License
MIT License
Categories
Productivity, Developer Tools, Design, Workplace, AI, Search, API, Frontend, Communication
Tags
#web

Jump to

- 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

Setting up with Highlight

This MCP is not yet compatible with Highlight’s one-click setup. However, you can still use it with Highlight by following these steps:

  1. Download and install Highlight from highlightai.com/download
  2. Navigate to the plugins tab and select "Add Custom Plugin"
  3. Configure the plugin with the settings below
    Plugin Name Notion
    Command (node, npx, python, etc.) /Users/username/Projects/notion-mcp/.venv/bin/python
    Arguments
    • Argument 1 -m
    • Argument 2 notion_mcp
    Environment
    • NOTION_API_KEY your_notion_integration_token

    Please refer to the README for specific instructions on how to obtain API keys or other required environment variables.

  4. Enable "Start Automatically" if you want the plugin to start when Highlight launches

From the repository

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

1. Go to https://www.notion.so/my-integrations
2. Create a new integration with appropriate capabilities (read/write as needed)
3. Copy the integration token
4. Add it to your .env file in the project root directory:

NOTION_API_KEY=your_notion_integration_token

5. Share your Notion databases with the integration (from the database's "Share" menu)

To install Notion Integration Server for Claude Desktop automatically via Smithery:

npx -y @smithery/cli install @ccabanillas/notion-mcp --client claude

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, using 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:

NOTION_API_KEY=your_notion_integration_token



pytest

Claude Desktop / Cursor

Paste into your MCP client config file to install this server.

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

Linux

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

Macos

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

Windows

{
    "cwd": "/Users/username/Projects/notion-mcp",
    "env": {
        "NOTION_API_KEY": "your_notion_integration_token"
    },
    "args": [
        "-m",
        "notion_mcp"
    ],
    "command": "/Users/username/Projects/notion-mcp/.venv/Scripts/python.exe"
}

Notion MCP Server

smithery badge

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

Installing via Smithery

To install Notion Integration Server for Claude Desktop automatically via Smithery:

npx -y @smithery/cli install @ccabanillas/notion-mcp --client claude

Manual 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, using 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:

NOTION_API_KEY=your_notion_integration_token

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

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:

1. Go to https://www.notion.so/my-integrations
2. Create a new integration with appropriate capabilities (read/write as needed)
3. Copy the integration token
4. Add it to your .env file in the project root directory:

NOTION_API_KEY=your_notion_integration_token

5. Share your Notion databases with the integration (from the database's "Share" menu)

Contributing

1. Fork the repository
2. Create your feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add some amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. 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 danhilse, I referenced his notion-mcp-server project

No reviews yet — be the first

Sign in to leave a review

Use Google, GitHub, or an email account so ratings stay tied to real people.

Email sign in

No reviews posted yet.

Install

Add to Claude Desktop or Cursor

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

More like this

Similar MCP servers you might find useful

Browse category

Time

A Model Context Protocol server that provides time and timezone conversion capabilities. It enables LLMs to get current time information and perform timezone…

88.2k
Productivity

Git

A Model Context Protocol (MCP) server that provides tools for LLMs to read, search, and manipulate Git repositories. It enables automated repository…

88.1k
Developer Tools

Context 7

Official Context7 MCP server that brings up-to-date, version-specific library documentation and code examples into AI coding prompts.

58.7k
Developer Tools