Notion MCP

Interact with your Notion by prompting Claude. Add your own tools and manage Notion with more comfort :)

Introduction

I created this project since I really enjoy using Notion, however, it seemed like a lot of stuff can be simplified by just creating MCP server over Notion API and letting the LLM manage the content there.

Example: If I want to add multiple entries to my expense tracker, I have to repeatedly click multiple buttons, sending one short message to the LLM solves it.

You can also simplify your workflow by adding your own tools. I tried to keep the code as modular as possible so that adding new tools is pretty straightforward. Below I share the steps that have to be done in order to do so.

---

Getting Started

1. Clone this repository

git clone https://github.com/dkoterwa/notion_mcp.git
cd notion_mcp

2. Install uv

Install uv if you don’t already have it.

3. Sync dependencies

Reproduce the environment by executing uv sync.

4. Add server to Claude config

First, in the Claude app, go to the Developer settings and click Edit Config button.

<div align="center"> <div style="display: inline-block; text-align: left;"> <img src="media/edit_config.png" width="720"> </div><br><br> </div>

You will be taken to claude_desktop_config.json file. Open it and paste the Notion MCP config:

{
  "mcpServers": {
    "notion_mcp": {
      "command": "<path to uv, e.g. /Users/user/.local/bin/uv>",
      "args": [
        "--directory",
        "<path to the repository root directory>",
        "run",
        "notion_mcp/run.py"
      ],
      "env": {
        "PYTHONPATH": "<path to the repository root directory>"
      }
    }
  }
}

5. Create .env file and place your Notion API key inside

In the root directory of repository execute:

echo NOTION_TOKEN=<your API key> > .env

Please go there and follow the steps to set up your Notion integration and get your API key if you don't know how to do it.

At the end, you should see that Claude has access to your local notion_mcp server. Make sure it's turned on: <div align="center"> <div style="display: inline-block; text-align: left;"> <img src="media/claude_integration.png" width="720"> </div><br><br> </div>

Adding Your Tools

Adding your own tools is really simple. Just go to /tools and then to the specific Notion data structure that you would like to implement new tool in. Then, add a new tool method to the function responsible for registering the tools of given data structure.

Let's assume I would like to add a tool returning current time. To do this, I add a method under register_util_tools in /tools/utils.py:

  def register_util_tools(mcp, calls):
      @mcp.tool()
      async def get_today() -> str:
          """
          Get today's date in ISO format (YYYY-MM-DD).
          """
          from datetime import date

          return date.today().isoformat()

+     @mcp.tool()
+     async def get_current_time() -> str:
+         """
+         Get the current local time in HH:MM:SS format.
+         """
+         from datetime import datetime
+         return datetime.now().strftime("%H:%M:%S")

That's it! Now Claude should have access to the get_current_time tool.

You can always turn off the tools I designed by changing the enable argument in the @mcp.tool decorator:

@mcp.tool(enabled=False)
def maintenance_tool():
    """This tool is currently under maintenance."""
    return "This tool is disabled."

Read more in the FastMCP documentation.

Current functionalities

<div align="center"> <div style="display: inline-block; text-align: left;"> <b>Create pages, and add or edit content.</b><br> <img src="media/recipes.gif" width="720"> </div><br><br>

<div style="display: inline-block; text-align: left;"> <b>Organize your calendar directly from the Claude chat window.</b><br> <img src="media/calendar.gif" width="720"> </div><br><br>

<div style="display: inline-block; text-align: left;"> <b>Manage your expenses without going to Notion and doing it manually.</b><br> <img src="media/expense_tracker.gif" width="720"> </div> </div>

Contribution

Please feel free to create an issue and ask if anything is not understandable for you. Contributions are welcome via pull requests. I plan to expand this project further only when I decide to automate additional Notion functionality that I use frequently.