mcpField
N
notion-mcp

notion-mcp

Local
github.com/BadhansenMemory & Knowledge31Updated 62w ago
Repository

About notion-mcp

notion-mcp is a simple MCP server that uses the Notion API to manage a personal todo list. It is aimed at users who want to view, add and complete Notion tasks from Claude Desktop. The server is written in Python and configured through a .env file and the Claude Desktop config.

Key features

  1. 01Lists all todo tasks from a Notion workspace
  2. 02Adds new tasks to a Notion page
  3. 03Marks tasks complete by task ID
  4. 04Reads Notion credentials from a .env file

Use cases

  1. 01Reviewing a personal todo list inside Claude Desktop
  2. 02Adding tasks to a Notion database from a chat
  3. 03Marking finished tasks as complete in Notion

MCP support

The server runs as an MCP server and exposes the show_all_todos, add_todo and complete_todo tools to MCP clients such as Claude Desktop.

Configuration

Local server config is the same for every client. Copy it into your client’s MCP config file.

mcp.json · Universal config
{
  "mcpServers": {
    "notion-mcp-badhansen": {
      "command": "npx",
      "args": [
        "-y",
        "@smithery/cli"
      ]
    }
  }
}
Run commandnpx -y @smithery/cli

Local servers need a runtime on your machine (e.g. Node.js 18+). Config file locations differ by client; see your client’s docs.

Packages
npm@smithery/cli

Tools

No tool list yet

Local servers expose tools only once running on your machine, and the maintainer has not provided a tool list.

Details

From the project 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:

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
  1. Set up Python environment:
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:
cp .env.example .env
  1. 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"
  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.
{
    "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.

Comments

Markdown supported

New to MCP?

From what the protocol is to installing your first server, these answers cover most first questions.

An open protocol that defines how AI applications connect to external tools and data in a uniform way. Clients talk to the model; MCP servers provide tools, resources and prompt templates. They exchange standard messages, so one server can be reused by many clients.