Operating Notion via Claude Desktop Using MCP!

Introduction

Recently, MCP was announced by Anthropic, and you might be wondering, "What exactly can it do?" In this article, we’ll explore one practical example of using MCP to operate Notion directly from Claude Desktop.

Background

I had previously submitted a pull request to implement a Notion server in the MCP server project, planning to write a detailed guide once it was merged. However, it seems MCP is moving toward a decentralized hosting model for scalability, instead of managing all servers centrally. As my PR may be closed, I decided to write this guide to ensure that others can still use it. (See the discussion here)

the pull request here:

https://github.com/modelcontextprotocol/servers/pull/129

Preparation

Setting Up the MCP Notion Server

I’ve created a repository to make it easier for you to get started. Clone it from the link below:

git clone https://github.com/suekou/mcp-notion-server.git

Next, run the following commands:

cd notion
npm run build
npm link

After execution, make sure the file notion/build/index.js is successfully created.

Preparing a Notion API Token

To allow the MCP server to access Notion, generate an API token. Go to the Integrations page and select New Integration.

Fill in the integration name, choose a workspace, and keep the Type as Internal (default).

Once the integration is created, go to its details page and copy the token by clicking Show → Copy:

Editing claude_desktop_config.json

Edit the claude_desktop_config.json file located at:

code ~/Library/Application\ Support/Claude/claude_desktop_config.json

In this file, add the path to the notion/build/index.js file you built earlier (e.g., /Users/<YOUR_USERNAME>/Desktop/mcp-notion-server/notion/build/index.js) under args, and paste the API token under NOTION_API_TOKEN like this:

{
  "mcpServers": {
    "notion": {
      "command": "node",
      "args": [
        "Path to the built file"
      ],
      "env": {
        "NOTION_API_TOKEN": "Your token"
      }
    }
  }
}

If you’re configuring other servers alongside this, your configuration might look like this:

{
  "mcpServers": {
    "sqlite": {
      "command": "uvx",
      "args": [
        "mcp-server-sqlite",
        "--db-path",
        "/Users/USER_NAME/test.db"
      ]
    },
    "notion": {
      "command": "node",
      "args": [
        "/Users/USER_NAME/Desktop/mcp-notion-server/notion/build/index.js"
      ],
      "env": {
        "NOTION_API_TOKEN": "API_TOKEN"
      }
    }
  }
}

Connecting the Integration

In the workspace you configured earlier, create a new page. Then click on the … menu in the upper-right corner and select Connect to, followed by your integration.

Next, copy the page ID from the URL. For example, if the URL is:

https://www.notion.so/mcp-test-notion1234server567apiintegration890

The last 32-character alphanumeric string (notion1234server567apiintegration890) is your page ID.

Let’s Try It Out!

Save an Article

Restart Claude Desktop if it’s already open. After restarting, click the hammer icon, and check if "notion" appears under From Server. If it does, you’re ready to go.

Now Let's ask Claude to write an article.

Once done, send the message:

"I want to save this content to Notion with <Your Page ID>."

Claude will prompt you for tool usage permissions—approve it.

After execution, you should see the article saved to your Notion page:

Using Databases

Create a database in Notion. Here’s an example where I asked Claude to create a movie database:

Add some sample entries:

Now, ask Claude:

"Tell me movies rated ⭐️⭐️⭐️⭐️⭐️."

It will retrieve and list only the 5-star movies:

Conclusion

This article introduced just a few features of MCP Notion Server, but there’s so much more you can do with it. Experiment with it and explore its potential!

If you've customized the server or discovered new use cases, I'd love to hear about your findings!
Thank you for reading! 👋

Comments

[patrick-xin]

Thanks for sharing!

[Harrison]

I have identified the cause of the error. The field in claude_desktop_config.json should be NOTION_API_TOKEN instead of NOTION_API_KEY, as the parameter in the index.js file is NOTION_API_TOKEN.

The correct and complete claude_desktop_config.json should look like this:

{
  "mcpServers": {
    "notion": {
      "command": "/opt/homebrew/bin/node",
      "args": ["/Users/xxxx/mcp-notion-server/notion/build/index.js"],
      "env": {
        "NOTION_API_TOKEN": "xxxxx",
        "NODE_ENV": "production"
      }
    }
  }
}

[Harrison]

I recently followed all the installation and configuration steps for the Claude desktop app, including setting up the claude_desktop_config.json file with the correct API key and absolute path to index.js. However, I’m encountering an issue where the app shows "Notion MCP server is disconnected" on my MacBook with an M1 chip.

Here are some details about my setup and the troubleshooting steps I’ve tried:

1. Verified that the Notion MCP server is running and restarted it manually.
2. Checked Node.js compatibility and ensured I’m using the latest LTS version.
3. Confirmed the absolute path to index.js in the configuration file is accurate.
4. Validated the API key by testing it with external tools like Postman.
5. Ensured a stable internet connection and temporarily disabled VPN/firewall.
6. Installed Rosetta 2 on my M1 MacBook.
7. Rebuilt dependencies by deleting the node_modules folder and reinstalling them.
8. Reviewed logs for errors but couldn’t pinpoint the issue.
9. Enabled debug mode for more detailed output.
10. Checked for potential compatibility issues with the M1 chip.
11. Reinstalled the Claude desktop app as a last resort.

Despite these efforts, the issue persists. Could you please provide any additional guidance or insights into what might be causing the disconnection? Are there any specific configurations or known issues with the M1 architecture that I should be aware of?