notion-mcp

notion-mcp

An MCP server for managing Notion to-do lists via API integration.

View on GitHub
27
Stars
4
Forks
27
Watchers
2
Issues
notion-mcp provides a Model Context Protocol (MCP) server that connects with Notion's API to help users manage their personal to-do lists. It enables querying, adding, and updating tasks directly from Notion through a standardized MCP interface, and is designed for integration with tools like Claude Desktop. The project is set up for easy deployment via Smithery and supports OAuth credentials and per-user configuration.

Key Features

MCP-compliant server interface
Integration with Notion API for tasks
Show, add, and complete tasks programmatically
Easy installation via Smithery CLI
Configurable credentials and options via .env
Supports Claude Desktop integration
Visual demo and usage guide
Python 3.11+ support
Sample configuration for developer setup
Function-based task operations

Use Cases

Programmatic management of Notion to-do lists
Automated task tracking and updates in Notion
Integrating Notion task workflows with Claude Desktop
Synchronizing AI-driven tools with Notion workspaces
Streamlining personal productivity via API automation
Developing plugins for AI assistants that manipulate Notion
Enabling voice agents or bots to interact with Notion tasks
Custom dashboard or productivity tool integrations with Notion
Automating repetitive task creation based on external triggers
Using as a template for building other MCP providers for productivity tools

README

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:

bash
npx -y @smithery/cli install @Badhansen/notion-mcp --client claude
  1. Clone the repository:
sh
git clone https://github.com/Badhansen/notion-mcp.git
cd notion-mcp
  1. Set up Python environment:
sh
uv venv
source .venv/bin/activate
uv pip install -e .
  1. Create a Notion integration:
  2. 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:
sh
cp .env.example .env
  1. Configure Notion credentials in .env:
markdown
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"
  1. 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.
json
{
    "mcpServers": {
        "notion-mcp": {
            "command": "uv",
            "args": [
                "--directory",
                "/Users/username/Projects/Python/notion-mcp/src" /* Path to your project */,
                "run",
                "server.py"
            ]
        }
    }
}

Development

Project structure:

markdown
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:

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

Add Task

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

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

Update Task

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

json
{
    "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.

Star History

Star History Chart

Repository Owner

Badhansen
Badhansen

User

Repository Details

Language Python
Default Branch master
Size 9,908 KB
Contributors 3
License MIT License
MCP Verified Nov 12, 2025

Programming Languages

Python
93.78%
Dockerfile
6.22%

Tags

Task Management python-server Claude Desktop API automation productivity

Join Our Newsletter

Stay updated with the latest AI tools, news, and offers by subscribing to our weekly newsletter.

We respect your privacy. Unsubscribe at any time.

Related MCPs

Discover similar Model Context Protocol servers

  • Notion MCP Integration

    Notion MCP Integration

    Integrate your minimal Notion todo list with Claude via Model Context Protocol.

    Notion MCP Integration provides a simple MCP server that enables users to manage a minimalist Notion todo list through Claude, leveraging Notion's API. It supports adding, viewing, and completing tasks according to a specific Notion database structure. Designed for personal use, it allows users to interact with their tasks using natural language through Claude Desktop. The tool is easily customizable for different Notion databases by modifying the server implementation.

    • ⭐ 202
    • MCP
    • danhilse/notion_mcp
  • Notion MCP Server

    Notion MCP Server

    Enable LLMs to interact with Notion using the Model Context Protocol.

    Notion MCP Server allows large language models to interface with Notion workspaces through a Model Context Protocol server, supporting both data retrieval and editing capabilities. It includes experimental Markdown conversion to optimize token usage for more efficient communication with LLMs. The server can be configured with environment variables and controlled for specific tool access. Integration with applications like Claude Desktop is supported for seamless automation.

    • ⭐ 834
    • MCP
    • suekou/mcp-notion-server
  • MCP Obsidian Server

    MCP Obsidian Server

    Integrate Obsidian note management with AI models via the Model Context Protocol.

    MCP Obsidian Server acts as a bridge between Obsidian and AI models by providing an MCP-compatible server interface. It enables programmatic access to Obsidian vaults through a local REST API, allowing operations like listing files, searching, reading, editing, and deleting notes. Designed to work with Claude Desktop and other MCP-enabled clients, it exposes a set of tools for efficient note and content management within Obsidian.

    • ⭐ 2,394
    • MCP
    • MarkusPfundstein/mcp-obsidian
  • Jotdown

    Jotdown

    MCP Server for Notion Page Creation and mdBook Generation

    Jotdown is an MCP server enabling large language models to interact seamlessly with Notion and generate markdown books (mdBooks). It allows LLMs to create or update Notion pages and manage the entire process of markdown book creation, including structure and navigation. Leveraging the Model Context Protocol, it provides tools for consistent and intelligent context handling between LLMs and external content platforms.

    • ⭐ 19
    • MCP
    • Harry-027/JotDown
  • Things MCP Server

    Things MCP Server

    Seamless Model Context Protocol integration for managing Things app todos and projects.

    Things MCP Server enables AI assistants to interact with the Things productivity app using the Model Context Protocol (MCP). It offers comprehensive support for Things' URL scheme, allowing creation, updating, and management of todos and projects through standardized commands. The server supports batch operations, advanced organization features, and natural language scheduling, making task automation efficient for MCP-compatible clients.

    • ⭐ 6
    • MCP
    • jimfilippou/things-mcp
  • TickTick MCP

    TickTick MCP

    MCP server for AI-powered TickTick task management integration

    TickTick MCP is a Model Context Protocol (MCP) server that enables standardized integration of TickTick's task management features with AI assistants and developer applications. It allows programmatic access to create, update, retrieve, complete, or delete tasks and projects in TickTick via Python. Using this MCP server, AI systems can leverage TickTick's API to help automate and manage user's to-do lists and projects through natural language or other interfaces.

    • ⭐ 6
    • MCP
    • ekkyarmandi/ticktick-mcp
    • View all Alternatives

    Didn't find tool you were looking for?

    Be as detailed as possible for better results