notion

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

Installation

Run this command in your terminal to add the MCP server to Claude Code.

Run in terminal:

Command

claude mcp add --transport stdio badhansen-notion-mcp uv --directory /path/to/your/notion-mcp/src run server.py \
  --env PAGE_ID="The Notion page or database ID to manage" \
  --env NOTION_TOKEN="Your Notion integration token" \
  --env NOTION_VERSION=""YYYY-MM-DD" format, e.g., 2022-06-28" \
  --env NOTION_BASE_URL="https://api.notion.com/v1"

How to use

This MCP server, notion-mcp, connects to the Notion API to help you manage your personal todo list directly via MCP interactions. It exposes functions to query and manipulate Notion tasks, enabling you to view all tasks, add new tasks, and mark tasks as completed. After starting the server through the UV (Python) runtime, you can issue structured MCP requests to call the available capabilities (e.g., show_all_todos, add_todo, complete_todo) and receive consistent responses that reflect changes in your Notion workspace.

How to install

Prerequisites:

Python 3.11 or higher
Access to the Notion API with an integration token
Notion page/database prepared for your todos

Installation steps:

Clone the repository: git clone https://github.com/Badhansen/notion-mcp.git cd notion-mcp
Set up a Python virtual environment and install in editable mode: uv venv source .venv/bin/activate uv pip install -e .
Create and configure environment variables (see .env.example): cp .env.example .env

Edit .env with your credentials and IDs
Start the MCP server via UV (Python): uv run --directory /path/to/notion-mcp/src server.py
If you’re using Claude Desktop, ensure your claude_desktop_config.json references the UV-based server as shown in the configuration example.

Note: If you prefer a Smithery-based installation, you can install via Smithery CLI as demonstrated in the README: npx -y @smithery/cli install @Badhansen/notion-mcp --client claude

Additional notes

Tips and common issues:

Ensure NOTION_TOKEN has sufficient permissions for the pages/databases you intend to manage.
The PAGE_ID should correspond to the target page or database containing your todos.
NOTION_VERSION should be set to a compatible Notion API version (e.g., 2022-06-28).
If you modify src/server.py or dependencies, re-run uv pip install -e . to apply changes.
When configuring Claude Desktop, you may need to adjust the Notion server configuration under Developer -> Edit Config to point to your local UV-based server.
Use the provided MCP actions: show_all_todos, add_todo, complete_todo to interact with Notion data programmatically.

Related MCP Servers

mcp-vegalite

MCP server from isaacwasserman/mcp-vegalite-server

github-chat

A Model Context Protocol (MCP) for analyzing and querying GitHub repositories using the GitHub Chat API.

nautex

MCP server for guiding Coding Agents via end-to-end requirements to implementation plan pipeline

pagerduty

PagerDuty's official local MCP (Model Context Protocol) server which provides tools to interact with your PagerDuty account directly from your MCP-enabled client.

futu-stock

mcp server for futuniuniu stock

mcp -boilerplate

Boilerplate using one of the 'better' ways to build MCP Servers. Written using FastMCP