home / mcp / notion mcp server

Notion MCP Server

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

Installation

Add the following to your MCP client configuration file.

Configuration

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

You can run a lightweight MCP server that connects Notion to your personal todo workflow. This server exposes a simple set of tasks controls and integrates with Notion’s API so you can view, add, and complete tasks directly from your MCP client.

How to use

You connect to the Notion MCP server from an MCP client. The server exposes a few core actions: show all tasks, add a new task, and mark a task as complete. Use these actions through your MCP client’s standard request/response interface. When you invoke the actions, the server communicates with Notion using the configured Notion token and page ID, returning task data or acknowledging updates.

How to install

Prerequisites: Python 3.11 or higher, a Notion account with API access, a Notion integration token, a Notion page to manage, and an environment capable of running the MCP server (Claude Desktop is supported). Ensure you have a working Python environment and an MCP runtime such as UV to host the server.

Install via Smithery to integrate with Claude Desktop automatically:

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

Configuration and runtime setup

Create and configure the environment and runtime so the MCP server can reach Notion. You will set up environment variables for Notion access and provide the path to the server code that will run under UV.

Place the following environment variables in a .env file (example values shown):

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"

Claude Desktop configuration example

To run the server locally with Claude Desktop, add the MCP server configuration in Claude Desktop settings.

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

Tools and endpoints

The server exposes a set of utility actions to manage Notion tasks. You can list all tasks, add a new task with a description, and update a task to mark it complete by referencing the task id.

Available tools

show_all_todos

Fetch and display all tasks from your Notion workspace.

add_todo

Create a new task in Notion with the given description.

complete_todo

Mark a task as completed by providing its task_id.