Notion

by badhansen

7 stars
Not rated
GitHub

About

Integrates with Notion's API to manage personal todo lists, enabling task creation, retrieval, and automation within specified Notion pages.

Details

Author
badhansen
Repository
Badhansen/notion-mcp
GitHub stars
7
License
MIT License
Categories
Productivity, Other, Project Management, Design, Workplace, Developer Tools, Communication, Frontend, Database
Tags
#web

Jump to

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.) uv
    Arguments
    • Argument 1 --directory
    • Argument 2 /Users/username/Projects/Python/notion-mcp/src
    • Argument 3 run
    • Argument 4 server.py
    Environment
    • PAGE_ID <your-notion-page-id>
    • NOTION_TOKEN <your-notion-api-token>
    • NOTION_VERSION 2022-06-28
    • NOTION_BASE_URL https://api.notion.com/v1

    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

1. Create .env file:

cp .env.example .env

2. Configure Notion credentials in .env:

NOTION_TOKEN=<your-notion-api-token>
PAGE_ID=<your-notion-page-id>
NOTION_VERSION="2022-06-28"
NOTION_BASE_URL="https://api.notion.com/v1"

3. To use it with Claude Desktop as intended you need to adjust your claude_desktop_config.json file.
Go to Claude Desktop -> Settings -> Developer -> Edit Config. Now add the Notion server configuration.

{
    "mcpServers": {
        "notion-mcp": {
            "command": "uv",
            "args": [
                "--directory",
                "/Users/username/Projects/Python/notion-mcp/src" / Path to your project /,
                "run",
                "server.py"
            ]
        }
    }
}

To install Notion MCP for Claude Desktop automatically via Smithery:

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

1. Clone the repository:

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

2. Set up Python environment:

uv venv
source .venv/bin/activate
uv pip install -e .

3. Create a Notion integration:
- Go to https://www.notion.so/my-integrations
- Create new integration
- Copy the API key
4. Share your database/page with the integration:
- Open your notion workspace with a database/table present or a page.
- Click "..." menu → "Add connections"
- Select your integration (Search by name)

show_all_todos

Show all tasks from your Notion workspace. This function does not require any parameters.

add_todo

Add a new task to your Notion workspace. Parameters: task (string) - Your task description.

complete_todo

Update an existing task in your Notion workspace. Parameters: task_id (string) - The ID of the task to be marked as complete.

Claude Desktop / Cursor

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

{
    "mcpServers": {
        "notion": {
            "env": {
                "PAGE_ID": "<your-notion-page-id>",
                "NOTION_TOKEN": "<your-notion-api-token>",
                "NOTION_VERSION": "2022-06-28",
                "NOTION_BASE_URL": "https://api.notion.com/v1"
            },
            "args": [
                "--directory",
                "/Users/username/Projects/Python/notion-mcp/src",
                "run",
                "server.py"
            ],
            "command": "uv"
        }
    }
}

Linux

{
    "env": {
        "PAGE_ID": "<your-notion-page-id>",
        "NOTION_TOKEN": "<your-notion-api-token>",
        "NOTION_VERSION": "2022-06-28",
        "NOTION_BASE_URL": "https://api.notion.com/v1"
    },
    "args": [
        "--directory",
        "/Users/username/Projects/Python/notion-mcp/src",
        "run",
        "server.py"
    ],
    "command": "uv"
}

Macos

{
    "env": {
        "PAGE_ID": "<your-notion-page-id>",
        "NOTION_TOKEN": "<your-notion-api-token>",
        "NOTION_VERSION": "2022-06-28",
        "NOTION_BASE_URL": "https://api.notion.com/v1"
    },
    "args": [
        "--directory",
        "/Users/username/Projects/Python/notion-mcp/src",
        "run",
        "server.py"
    ],
    "command": "uv"
}

Windows

{
    "env": {
        "PAGE_ID": "<your-notion-page-id>",
        "NOTION_TOKEN": "<your-notion-api-token>",
        "NOTION_VERSION": "2022-06-28",
        "NOTION_BASE_URL": "https://api.notion.com/v1"
    },
    "args": [
        "--directory",
        "/Users/username/Projects/Python/notion-mcp/src",
        "run",
        "server.py"
    ],
    "command": "uv"
}

notion-mcp

Ask DeepWiki

Trust Score
smithery badge

A simple Model Context Protocol (MCP) server that integrates with Notion's API to manage my personal todo list.

Demo

Demo

Visual Guide

Notion MCP Query 1

Notion MCP Query 1

Notion MCP Query 2

Notion MCP Query 1

Notion MCP Query 3

Notion MCP Query 1

Prerequisites

- Python 3.11 or higher
- A Notion account with API access
- A Notion integration token
- A Notion page where you want to manage your todo list
- Claude Desktop clint

Setup

Installing via Smithery

To install Notion MCP for Claude Desktop automatically via Smithery:

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

1. Clone the repository:

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

2. Set up Python environment:

uv venv
source .venv/bin/activate
uv pip install -e .

3. Create a Notion integration:
- Go to https://www.notion.so/my-integrations
- Create new integration
- Copy the API key
4. Share your database/page with the integration:
- Open your notion workspace with a database/table present or a page.
- Click "..." menu → "Add connections"
- Select your integration (Search by name)

Configuration

1. Create .env file:

cp .env.example .env

2. Configure Notion credentials in .env:

NOTION_TOKEN=<your-notion-api-token>
PAGE_ID=<your-notion-page-id>
NOTION_VERSION="2022-06-28"
NOTION_BASE_URL="https://api.notion.com/v1"

3. To use it with Claude Desktop as intended you need to adjust your claude_desktop_config.json file.
Go to Claude Desktop -> Settings -> Developer -> Edit Config. Now add the Notion server configuration.

{
    "mcpServers": {
        "notion-mcp": {
            "command": "uv",
            "args": [
                "--directory",
                "/Users/username/Projects/Python/notion-mcp/src" / Path to your project /,
                "run",
                "server.py"
            ]
        }
    }
}

Development

Project structure:

notion-mcp/
├── docs/
├── src/
│ └── server.py
├── .env
├── .python-version
├── README.md
├── pyproject.toml
└── uv.lock

Support Functions

Show Tasks

To show all tasks from your Notion workspace, use the show_all_todos function:

{
    "name": "show_all_todos",
    "arguments": {}
}

Add Task

To add a new task to your Notion workspace, use the add_todo function:

{
    "name": "add_todo",
    "arguments": {
        "task": "Your task description"
    }
}

Update Task

To update an existing task in your Notion workspace, use the complete_todo function:

{
    "name": "complete_todo",
    "arguments": {
        "task_id": "your-task-id"
    }
}

Contributing

1. Fork the repository
2. Create feature branch
3. Submit pull request

License

MIT License. See LICENSE file for details.

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": {
            "env": {
                "PAGE_ID": "<your-notion-page-id>",
                "NOTION_TOKEN": "<your-notion-api-token>",
                "NOTION_VERSION": "2022-06-28",
                "NOTION_BASE_URL": "https://api.notion.com/v1"
            },
            "args": [
                "--directory",
                "/Users/username/Projects/Python/notion-mcp/src",
                "run",
                "server.py"
            ],
            "command": "uv"
        }
    }
}

More like this

Similar MCP servers you might find useful

Browse category

Sequential Thinking

Sequential Thinking is an MCP server that provides a tool for dynamic and reflective problem-solving through a structured, step-by-step thinking process. It is…

88.2k
Other

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

Filesystem

Filesystem is a Node.js server that implements the Model Context Protocol (MCP) for filesystem operations. It enables AI assistants to read, write, and manage…

88.1k
Other