# 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
```bash
git clone https://github.com/dkoterwa/notion_mcp.git
cd notion_mcp
```

### 2. Install `uv`
Install [uv](https://docs.astral.sh/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:
```json
{
  "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:
```bash
echo NOTION_TOKEN=<your API key> > .env
```

Please go [there](https://developers.notion.com/docs/create-a-notion-integration) 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`:

```diff
  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:

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

Read more in the [FastMCP documentation](https://gofastmcp.com/getting-started/welcome).



## 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.