Notion MCP

GitHub
  • Note Taking
Python
MIT
56
-
security - not tested
A
license - permissive license (MIT)
-
quality - not tested

A simple Model Context Protocol (MCP) server that integrates with Notion's API to manage my personal todo list through Claude.

  1. Tools
  2. Prompts
  3. Resources
  4. Server Configuration
  5. README.md

Prompts

Interactive templates invoked by user choice

NameDescription

No prompts

Resources

Contextual data attached and managed by the client

NameDescription

No resources

Tools

Functions exposed to the LLM to take actions

NameDescription

No tools

Server Configuration

Describes the environment variables required to run the server.

NameRequiredDescriptionDefault
NOTION_API_KEYYesYour Notion integration API key
NOTION_DATABASE_IDYesYour Notion database ID
Need Help?View Source CodeReport Issue
README.md

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

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:
git clone https://github.com/yourusername/notion-mcp.git cd notion-mcp
  1. Set up Python environment:
python -m venv .venv source .venv/bin/activate # On Windows use: .venv\Scripts\activate uv pip install -e .
  1. Create a Notion integration:
  2. Share your database with the integration:
    • Open your todo database in Notion
    • Click "..." menu → "Add connections"
    • Select your integration
  3. Create a .env file:
NOTION_API_KEY=your-api-key-here NOTION_DATABASE_ID=your-database-id-here
  1. Configure Claude Desktop:
{ "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:
# From the project directory with virtual environment activated python -m notion_mcp
  1. 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

GitHub Badge

Glama performs regular codebase and documentation scans to:

  • Confirm that the MCP server is working as expected.
  • Confirm that there are no obvious security issues with dependencies of the server.
  • Extract server characteristics such as tools, resources, prompts, and required parameters.

Our directory badge helps users to quickly asses that the MCP server is safe, server capabilities, and instructions for installing the server.

Copy the following code to your README.md file:

Alternative MCP servers

  • zendesk-mcp-server

    -
    security
    F
    license
    -
    quality
    This server provides a comprehensive integration with Zendesk. Retrieving and managing tickets and comments. Ticket analyzes and response drafting. Access to help center articles as knowledge base.

  • jira-mcp-server

    -
    security
    -
    license
    -
    quality
    Tools for executing JQL queries. Tools for creating, editing, and deleting Jira tickets. Tools for listing Jira projects and statuses
    • Apple

  • airtable-mcp-server

    A
    security
    A
    license
    A
    quality
    A Model Context Protocol server that provides read and write access to Airtable databases. This server enables LLMs to inspect database schemas, then read and write records.
    MIT

  • mcp-notion-server

    -
    security
    A
    license
    -
    quality
    MCP Server for the Notion API, enabling Claude to interact with Notion workspaces.
    MIT