Notion MCP Integration

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