notion_mcp

# Notion MCP Integration 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. <p align="center"> <img src="assets/demo.gif" width="600"/> </p> ## Important Note This is a personal project designed for a very specific use case: my simple Notion todo list that has just three properties: - Task (title) - When (select with only two options: "today" or "later") - Checkbox (marks if completed) [Example Notion Database](https://danhilse.notion.site/14e5549555a08078afb5ed5d374bb656?v=14e5549555a081f9b5a4000cdf952cb9&pvs=4) 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. ## Features - Add new todo items - View all todos - View today's tasks - Check off a task as complete ## Prerequisites - Python 3.10 or higher - A Notion account - A Notion integration (API key) - A Notion database that matches the exact structure described above (or willingness to modify the code for your structure) ## Setup 1. Clone the repository: ```bash git clone https://github.com/yourusername/notion-mcp.git cd notion-mcp ``` 2. Set up Python environment: ```bash 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: ```env NOTION_API_KEY=your-api-key-here NOTION_DATABASE_ID=your-database-id-here ``` 6. Configure Claude Desktop: ```json { "mcpServers": { "notion-todo": { "command": "/path/to/your/.venv/bin/python", "args": ["-m", "notion_mcp"], "cwd": "/path/to/notion-mcp" } } } ``` ## Running the Server The server can be run in two ways: 1. Directly from the command line: ```bash # From the project directory with virtual environment activated python -m notion_mcp ``` 2. Automatically through Claude Desktop (recommended): - The server will start when Claude launches if configured correctly in `claude_desktop_config.json` - No manual server management needed - Server stops when Claude is closed 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. ## Usage Basic commands through Claude: - "Show all my todos" - "What's on my list for today?" - "Add a todo for today: check emails" - "Add a task for later: review project" ## Limitations - Only works with a specific Notion database structure - No support for complex database schemas - Limited to "today" or "later" task scheduling - No support for additional properties or custom fields - Basic error handling - No advanced features like recurring tasks, priorities, or tags ## Customization If you want to use this with a different database structure, you'll need to modify the `server.py` file, particularly: - The `create_todo()` function to match your database properties - The todo formatting in `call_tool()` to handle your data structure - The input schema in `list_tools()` if you want different options ## Project Structure ``` notion_mcp/ ├── pyproject.toml ├── README.md ├── .env # Not included in repo └── src/ └── notion_mcp/ ├── __init__.py ├── __main__.py └── server.py # Main implementation ``` ## License MIT License - Use at your own risk ## Acknowledgments - Built to work with Claude Desktop - Uses Notion's API