Notion

You can run a Notion MCP Server that exposes the official Notion SDK, enabling AI models to interact with Notion workspaces. This server is designed to be integrated with AI assistants so you can search, retrieve, create, and manage Notion content through familiar MCP client configurations.

How to use

Use the MCP client you already have (for example Claude Desktop, Cursor AI, or Claude.ai) and point it to the Notion MCP Server configuration. You can run the server locally with the standard npx command or configure it via a JSON setup for your assistant. Once the server is running, you will have access to Notion tools such as Search, Databases, Pages, Blocks, Users, Comments, and Link Previews to perform actions and fetch data from your linked Notion workspaces.

How to install

Prerequisites you need before installation:

• Node.js and npm installed on your machine.

Follow these steps to set up and run the MCP server locally using the CLI and an API key.

# Check Node.js and npm versions
node -v
npm -v

# Run the MCP server with your Notion API key
npx @ramidecodes/mcp-server-notion@latest -y --api-key=your-notion-integration-key

# Alternative: run with a .env file containing the API key
# Create a .env file with NOTION_API_KEY=your-notion-integration-key
npx @ramidecodes/mcp-server-notion@latest -y

Configuration and usage notes

You can also configure the server using JSON so your MCP client loads the server automatically.

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

Environment variable setup

If you prefer using a .env file to store your API key, create a file named .env in the server directory with the following content.

NOTION_API_KEY=your-notion-integration-key

Then start the server again using the same command as above without the --api-key flag.

## Security and access considerations

Only pages and databases explicitly shared with your integration are accessible. Share each page or database you want the AI to access, and remember that child pages inherit access from their parent pages.

## Troubleshooting

If you encounter errors such as “Failed to create client,” try the following steps to diagnose and resolve issues.

- On Windows, run the command with cmd /c before the npx command.

- On macOS or Linux, use the full path to npx if needed.

- Ensure the Notion integration key is correct and that the integration has access to the specific Notion pages or databases.

## Notes about capabilities

This MCP server provides the full Notion API support through the official SDK, offering tools for searching, querying databases, manipulating pages and blocks, handling user information, comments, and link previews.

## Available tools

### Search

Find pages or databases across Notion workspaces.

### Databases

Query and retrieve database entries.

### Pages

Create, retrieve, and update Notion pages.

### Blocks

Manage content blocks like paragraphs and lists.

### Users

List users and fetch user information.

### Comments

Create and list comments on Notion content.

### Link Previews

Create previews for URLs to enrich pages.