Notion MCP server

The Notion MCP Server provides integration between Notion workspaces and Large Language Models (LLMs). It enables structured interaction with Notion's API and includes features like Markdown conversion to optimize token usage and make interactions more efficient.

Installation and Setup

To get started with the Notion MCP Server, follow these steps:

Creating a Notion Integration

1. Visit the Notion Your Integrations page
2. Click "New Integration"
3. Name your integration and select appropriate permissions (e.g., "Read content", "Update content")
4. Copy the "Internal Integration Token" - you'll need this for configuration

Adding the Integration to Your Workspace

1. Open the Notion page or database you want the integration to access
2. Click the "···" button in the top right corner
3. Click the "Connections" button and select the integration you created

Configuring Claude Desktop

Add the following to your claude_desktop_config.json:

{
  "mcpServers": {
    "notion": {
      "command": "npx",
      "args": ["-y", "@suekou/mcp-notion-server"],
      "env": {
        "NOTION_API_TOKEN": "your-integration-token"
      }
    }
  }
}

Alternatively, if you've built the server locally:

{
  "mcpServers": {
    "notion": {
      "command": "node",
      "args": ["your-built-file-path"],
      "env": {
        "NOTION_API_TOKEN": "your-integration-token"
      }
    }
  }
}

Environment Variables

• NOTION_API_TOKEN (required): Your Notion API integration token
• NOTION_MARKDOWN_CONVERSION: Set to "true" to enable Markdown conversion, which reduces token consumption when viewing content

Usage

Command Line Arguments

You can specify which tools to enable using the --enabledTools argument:

node build/index.js --enabledTools=notion_retrieve_block,notion_retrieve_block_children,notion_retrieve_page,notion_query_database,notion_retrieve_database,notion_search,notion_list_all_users,notion_retrieve_user,notion_retrieve_bot_user,notion_retrieve_comments

This example enables only read-only tools.

Enabling Markdown Conversion

To reduce token consumption, you can enable Markdown conversion by setting the environment variable:

{
  "mcpServers": {
    "notion": {
      "command": "npx",
      "args": ["-y", "@suekou/mcp-notion-server"],
      "env": {
        "NOTION_API_TOKEN": "your-integration-token",
        "NOTION_MARKDOWN_CONVERSION": "true"
      }
    }
  }
}

When enabled, you can control the format on a per-request basis:

• Use "markdown" format for better readability when only viewing content
• Use "json" format when you need to modify the returned content

Available Tools

All tools support the optional format parameter (string, "json" or "markdown", default: "markdown").

Reading Content

• notion_retrieve_page

  • Retrieves information about a specific page
  • Required input: page_id (string)

• notion_retrieve_block

  • Retrieves information about a specific block
  • Required input: block_id (string)

• notion_retrieve_block_children

  • Retrieves the children of a specific block
  • Required input: block_id (string)
  • Optional inputs: start_cursor (string), page_size (number)

• notion_query_database

  • Queries a database
  • Required input: database_id (string)
  • Optional inputs: filter (object), sorts (array), start_cursor (string), page_size (number)

• notion_retrieve_database

  • Retrieves information about a specific database
  • Required input: database_id (string)

• notion_search

  • Searches pages or databases by title
  • Optional inputs: query (string), filter (object), sort (object), start_cursor (string), page_size (number)

Writing Content

• notion_append_block_children

  • Appends child blocks to a parent block
  • Required inputs: block_id (string), children (array)

• notion_delete_block

  • Deletes a specific block
  • Required input: block_id (string)

• notion_update_page_properties

  • Updates properties of a page
  • Required inputs: page_id (string), properties (object)

• notion_create_database

  • Creates a new database
  • Required inputs: parent (object), properties (object)
  • Optional input: title (array)

• notion_update_database

  • Updates information about a database
  • Required input: database_id (string)
  • Optional inputs: title (array), description (array), properties (object)

• notion_create_database_item

  • Creates a new item in a database
  • Required inputs: database_id (string), properties (object)

User-Related Tools

• notion_list_all_users

  • Lists all users in the workspace
  • Optional inputs: start_cursor (string), page_size (number)

• notion_retrieve_user

  • Retrieves information about a specific user
  • Required input: user_id (string)

• notion_retrieve_bot_user

  • Retrieves information about the bot user associated with the current token

Comment-Related Tools

• notion_create_comment

  • Creates a comment in Notion
  • Required input: rich_text (array)
  • Optional inputs: parent (object with page_id) or discussion_id (string)

• notion_retrieve_comments

  • Retrieves unresolved comments from a page or block
  • Required input: block_id (string)
  • Optional inputs: start_cursor (string), page_size (number)

Troubleshooting

If you encounter permission errors:

1. Ensure the integration has the required permissions
2. Verify that the integration is invited to the relevant pages or databases
3. Confirm the token and configuration are correctly set in claude_desktop_config.json

For Enterprise-specific features like user management, you may need to upgrade to Notion Enterprise plan and use an Organization API key.

How to install this MCP server

For Claude Code

To add this MCP server to Claude Code, run this command in your terminal:

claude mcp add-json "notion" '{"command":"npx","args":["-y","@suekou/mcp-notion-server"],"env":{"NOTION_API_TOKEN":"your-integration-token"}}'

See the official Claude Code MCP documentation for more details.

For Cursor

There are two ways to add an MCP server to Cursor. The most common way is to add the server globally in the ~/.cursor/mcp.json file so that it is available in all of your projects.

If you only need the server in a single project, you can add it to the project instead by creating or adding it to the .cursor/mcp.json file.

Adding an MCP server to Cursor globally

To add a global MCP server go to Cursor Settings > Tools & Integrations and click "New MCP Server".

When you click that button the ~/.cursor/mcp.json file will be opened and you can add your server like this:

{
    "mcpServers": {
        "notion": {
            "command": "npx",
            "args": [
                "-y",
                "@suekou/mcp-notion-server"
            ],
            "env": {
                "NOTION_API_TOKEN": "your-integration-token"
            }
        }
    }
}

Adding an MCP server to a project

To add an MCP server to a project you can create a new .cursor/mcp.json file or add it to the existing one. This will look exactly the same as the global MCP server example above.

How to use the MCP server

Once the server is installed, you might need to head back to Settings > MCP and click the refresh button.

The Cursor agent will then be able to see the available tools the added MCP server has available and will call them when it needs to.

You can also explicitly ask the agent to use the tool by mentioning the tool name and describing what the function does.

For Claude Desktop

To add this MCP server to Claude Desktop:

1. Find your 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. Add this to your configuration file:

{
    "mcpServers": {
        "notion": {
            "command": "npx",
            "args": [
                "-y",
                "@suekou/mcp-notion-server"
            ],
            "env": {
                "NOTION_API_TOKEN": "your-integration-token"
            }
        }
    }
}

3. Restart Claude Desktop for the changes to take effect