Notion MCP server

The Notion MCP Server enables AI models to interact with Notion workspaces through the Model Context Protocol, allowing seamless access to Notion content and functionality via the official Notion SDK.

Setting Up Your Notion Integration

Create a Notion Integration

1. Visit https://www.notion.so/my-integrations
2. Create a new integration
3. Copy the API key for later use

Connect Notion Pages to Your Integration

For your integration to access content, you must explicitly share pages or databases with it:

1. Navigate to the Notion page or database you want to access
2. Click the "Share" button in the top-right corner
3. In the "Add people, groups, or integrations" field, select your integration
4. Click "Invite"
5. Repeat for each page or database you want to make accessible

Note: Integrations only have access to pages and databases explicitly shared with them. Child pages automatically inherit access from parent pages.

Adding the MCP Server to Your AI Assistant

You can add this server to Claude Desktop, Cursor AI, or Claude.ai using either of these configuration methods:

Command Line Format

npx @ramidecodes/mcp-server-notion@latest -y --api-key=your-notion-integration-key

JSON Configuration Format

{
  "mcpServers": {
    "Notion": {
      "command": "npx",
      "args": [
        "@ramidecodes/mcp-server-notion@latest",
        "-y",
        "--api-key=your-notion-integration-key"
      ]
    }
  }
}

Replace your-notion-integration-key with your actual API key.

Where to Configure MCP Servers

• Claude Desktop: Settings > Advanced > Model Context Protocol
• Cursor AI: Settings > AI > MCP Servers
• Claude.ai (Web): Profile > Settings > API & Integrations > Model Context Protocol

Alternative Setup Methods

Using Environment Variables

Instead of passing the API key directly, you can use a .env file:

1. Create a .env file containing:

NOTION_API_KEY=your-notion-integration-key

2. Run the server without the API key parameter:

npx @ramidecodes/mcp-server-notion@latest -y

Command Line Options

OPTIONS:
  -h, --help              Show help message
  -v, --version           Show version information
  --verbose               Enable verbose logging
  --env-path <path>       Path to .env file
  --api-key <key>         Notion API key
  -y                      Skip confirmation prompts

Available Tools

The Notion MCP server provides these tools for interacting with Notion:

• Search: Find pages or databases
• Databases: Query and retrieve database entries
• Pages: Create, retrieve, and update pages
• Blocks: Manage content blocks (paragraphs, lists, etc.)
• Users: List users and get user information
• Comments: Create and list comments
• Link Previews: Create link previews for URLs

Troubleshooting

Common Issues

• "Failed to create client" errors:

  • On Windows, try using cmd /c before the npx command
  • On macOS/Linux, try using the full path to npx
  • Test the command in a terminal before adding it to your AI assistant

• "No access to resource" errors: Make sure you've shared the specific Notion page or database with your integration

• Integration not appearing in share menu: Try refreshing the page or restarting your browser

• Limited capabilities: Verify your integration has the appropriate capabilities enabled in the Notion integration settings

How to add this MCP server to 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 > MCP and click "Add new global MCP server".

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

{
    "mcpServers": {
        "cursor-rules-mcp": {
            "command": "npx",
            "args": [
                "-y",
                "cursor-rules-mcp"
            ]
        }
    }
}

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 explictly ask the agent to use the tool by mentioning the tool name and describing what the function does.