carterfawson/GTD-notion-mcp

Notion GTD MCP Server

A Model Context Protocol (MCP) server for managing Getting Things Done (GTD) tasks in Notion. This server provides Claude with tools to efficiently manage your task tracking system.

Features

Core GTD Operations

• Get tasks by list - Fetch all tasks from specific GTD lists (inbox, top priority, backlog, someday, waiting for)
• Quick inbox access - Instant access to inbox tasks for daily reviews
• Priority task management - Get all top priority tasks with due dates
• Move tasks - Move tasks between different GTD lists
• Bulk updates - Update multiple tasks at once during reviews
• Create tasks - Create new tasks with automatic inbox default

Review Functions

• Daily review - Get inbox items, today's tasks, and overdue tasks (excludes Done tasks)
• Weekly review - Comprehensive view including all lists, upcoming tasks, and goal alignment (excludes Done tasks)
• Goal-based search - Find tasks related to specific 2025 goals (excludes Done tasks)

Advanced Queries

• Overdue tasks - Find all tasks with past due dates from active lists (excludes Done tasks)
• Multi-filter search - Complex queries with multiple conditions
• Incomplete task finder - Find tasks missing priority or due dates

Note: All queries automatically exclude tasks from the "Done" list to focus on actionable items.

Prerequisites

• Python 3.10 or higher
• A Notion workspace with a GTD task database
• Notion API integration token
• Claude Desktop application

Setup Instructions

1. Clone and Set Up the Project

# Clone or create the project directory
cd notion-gtd-mcp

# Create a virtual environment
python -m venv venv

# Activate the virtual environment
# On macOS/Linux:
source venv/bin/activate
# On Windows:
venv\Scripts\activate

# Install the package
pip install -e .

2. Create Notion Integration

1. Go to https://www.notion.so/my-integrations
2. Click "New integration"
3. Give it a name: "GTD MCP Server"
4. Select your workspace
5. Give it these capabilities:
   • Read content
   • Update content
   • Insert content
6. Copy the Internal Integration Token

3. Connect Integration to Your Database

1. Open your "All Tasks" database in Notion
2. Click the "..." menu in the top right
3. Select "Add connections"
4. Search for and select your "GTD MCP Server" integration
5. If you have a "2025 Vision and Goals" page, repeat the process for that page

4. Configure Environment Variables

1. Copy env.template to .env:

   cp env.template .env
   

2. Edit .env and add your values:

   NOTION_API_KEY=your_notion_integration_token_here
   NOTION_DATABASE_ID=25f2afc3-a6e4-463f-ad58-7810bc03aaea
   NOTION_GOALS_PAGE_ID=your_2025_goals_page_id_here
   

   To find your database/page IDs:

   • Open the database/page in Notion
   • Look at the URL: https://notion.so/workspace/[DATABASE_ID]?v=[VIEW_ID]
   • Copy the ID portion (before the ?)

5. Test the Server

# Make sure virtual environment is activated
python -m notion_gtd_mcp

You should see the server start without errors.

6. Configure Claude Desktop

1. Find your Claude Desktop configuration file:

   • macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
   • Windows: %APPDATA%\Claude\claude_desktop_config.json
   • Linux: ~/.config/Claude/claude_desktop_config.json

2. Edit the configuration file to add the MCP server:

{
  "mcpServers": {
    "notion-gtd": {
      "command": "/path/to/your/notion-gtd-mcp/venv/bin/python",
      "args": ["-m", "notion_gtd_mcp"],
      "cwd": "/path/to/your/notion-gtd-mcp",
      "env": {
        "NOTION_API_KEY": "your_notion_integration_token",
        "NOTION_DATABASE_ID": "25f2afc3-a6e4-463f-ad58-7810bc03aaea",
        "NOTION_GOALS_PAGE_ID": "your_goals_page_id"
      }
    }
  }
}

Important: Replace /path/to/your/notion-gtd-mcp with the actual path to your project directory.

7. Restart Claude Desktop

After saving the configuration, completely quit and restart Claude Desktop. The GTD tools should now be available.

Usage Examples

Once configured, you can ask Claude to:

• "Show me all my inbox tasks"
• "Move task [ID] to top priority"
• "Create a new task: Review Q1 financial reports"
• "Show me my daily review"
• "Get all overdue tasks"
• "Find tasks related to my fitness goals"
• "Show me top priority tasks without due dates"
• "Bulk move these 5 tasks to backlog"

Database Structure Requirements

Your Notion database should have these properties:

• Name (Title) - The task title
• List (Select) - Options: inbox, top priority, backlog, someday, waiting for
• Priority (Select) - Options: high, medium, low
• Due Date (Date) - Task due date
• Notes (Text) - Additional task notes

Troubleshooting

Server won't start

• Check that all environment variables are set correctly
• Verify your Notion integration token is valid
• Ensure the database ID is correct

Can't see tools in Claude

• Make sure the configuration path points to your Python executable in the virtual environment
• Check that the server starts successfully when run manually
• Verify the configuration JSON is valid (no trailing commas, proper quotes)

Tasks not appearing

• Confirm the integration is connected to your database in Notion
• Check that your database has the required properties
• Verify the list names match exactly (case-sensitive)

Development

To add new features or modify the server:

1. Edit src/notion_gtd_mcp/server.py
2. Add new tools in the list_tools method
3. Implement the tool logic in the call_tool method
4. Add helper methods as needed

License

This project is provided as-is for personal use.