Skip to content
Back to search

notion_mcp

A simple MCP integration that allows Claude to read and manage a personal Notion todo list

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/danhilse--notion-mcp/badge.svg)](/listings/danhilse--notion-mcp)

HTML

<a href="/listings/danhilse--notion-mcp"><img src="/api/listings/danhilse--notion-mcp/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

1. Clone the repository:

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

2. Set up Python environment:

python -m venv .venv
source .venv/bin/activate  # On Windows use: .venv\Scripts\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 with the integration: - Open your todo database in Notion - Click "..." menu → "Add connections" - Select your integration

5. Create a `.env` file:

NOTION_API_KEY=your-api-key-here
NOTION_DATABASE_ID=your-database-id-here

6. Configure Claude Desktop:

{
  "mcpServers": {
    "notion-todo": {
      "command": "/path/to/your/.venv/bin/python",
      "args": ["-m", "notion_mcp"],
      "cwd": "/path/to/notion-mcp"
    }
  }
}

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 139 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

  1. # Notion MCP Integration
  2. A simple Model Context Protocol (MCP) server that integrates with Notion's API to manage my personal todo list through Claude. This is a basic implementation tailored specifically for my minimalist todo list setup in Notion.
  3. <p align="center">
  4. <img src="assets/demo.gif" width="600"/>
  5. </p>
  6. ## Important Note
  7. This is a personal project designed for a very specific use case: my simple Notion todo list that has just three properties:
  8. - Task (title)
  9. - When (select with only two options: "today" or "later")
  10. - Checkbox (marks if completed)
  11. [Example Notion Database](https://danhilse.notion.site/14e5549555a08078afb5ed5d374bb656?v=14e5549555a081f9b5a4000cdf952cb9&pvs=4)
  12. While you can use this as a starting point for your own Notion integration, you'll likely need to modify the code to match your specific database structure and requirements.
  13. ## Features
  14. - Add new todo items
  15. - View all todos
  16. - View today's tasks
  17. - Check off a task as complete
  18. ## Prerequisites
  19. - Python 3.10 or higher
  20. - A Notion account
  21. - A Notion integration (API key)
  22. - A Notion database that matches the exact structure described above (or willingness to modify the code for your structure)
  23. ## Setup
  24. 1. Clone the repository:
  25. ```bash
  26. git clone https://github.com/yourusername/notion-mcp.git
  27. cd notion-mcp
  28. ```
  29. 2. Set up Python environment:
  30. ```bash
  31. python -m venv .venv
  32. source .venv/bin/activate # On Windows use: .venv\Scripts\activate
  33. uv pip install -e .
  34. ```
  35. 3. Create a Notion integration:
  36. - Go to https://www.notion.so/my-integrations
  37. - Create new integration
  38. - Copy the API key
  39. 4. Share your database with the integration:
  40. - Open your todo database in Notion
  41. - Click "..." menu → "Add connections"
  42. - Select your integration
  43. 5. Create a `.env` file:
  44. ```env
  45. NOTION_API_KEY=your-api-key-here
  46. NOTION_DATABASE_ID=your-database-id-here
  47. ```
  48. 6. Configure Claude Desktop:
  49. ```json
  50. {
  51. "mcpServers": {
  52. "notion-todo": {
  53. "command": "/path/to/your/.venv/bin/python",
  54. "args": ["-m", "notion_mcp"],
  55. "cwd": "/path/to/notion-mcp"
  56. }
  57. }
  58. }
  59. ```
  60. ## Running the Server
  61. The server can be run in two ways:
  62. 1. Directly from the command line:
  63. ```bash
  64. # From the project directory with virtual environment activated
  65. python -m notion_mcp
  66. ```
  67. 2. Automatically through Claude Desktop (recommended):
  68. - The server will start when Claude launches if configured correctly in `claude_desktop_config.json`
  69. - No manual server management needed
  70. - Server stops when Claude is closed
  71. Note: When running directly, the server won't show any output unless there's an error - this is normal as it's waiting for MCP commands.
  72. ## Usage
  73. Basic commands through Claude:
  74. - "Show all my todos"
  75. - "What's on my list for today?"
  76. - "Add a todo for today: check emails"
  77. - "Add a task for later: review project"
  78. ## Limitations
  79. - Only works with a specific Notion database structure
  80. - No support for complex database schemas
  81. - Limited to "today" or "later" task scheduling
  82. - No support for additional properties or custom fields
  83. - Basic error handling
  84. - No advanced features like recurring tasks, priorities, or tags
  85. ## Customization
  86. If you want to use this with a different database structure, you'll need to modify the `server.py` file, particularly:
  87. - The `create_todo()` function to match your database properties
  88. - The todo formatting in `call_tool()` to handle your data structure
  89. - The input schema in `list_tools()` if you want different options
  90. ## Project Structure
  91. ```
  92. notion_mcp/
  93. ├── pyproject.toml
  94. ├── README.md
  95. ├── .env # Not included in repo
  96. └── src/
  97. └── notion_mcp/
  98. ├── __init__.py
  99. ├── __main__.py
  100. └── server.py # Main implementation
  101. ```
  102. ## License
  103. MIT License - Use at your own risk
  104. ## Acknowledgments
  105. - Built to work with Claude Desktop
  106. - Uses Notion's API

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.