notion

Notion MCP Server provides a comprehensive bridge between natural language prompts and Notion's data model. It exposes a suite of MCP tools that let your AI assistant read, create, update, and organize content in Notion, including pages, blocks, databases, comments, and user information. The server is designed to work with any MCP client (e.g., Cursor, Claude Desktop, Cline, Zed) and presents clear actions you can invoke through payloads. Typical workflows include creating new pages, updating page properties, appending content to blocks, querying databases, and managing comments and users. To start using it, run the server with the recommended command (for example via npx notion-mcp-server) and supply your Notion API token and target page or workspace as environment variables. Once running, your MCP client can send structured payloads that map to the provided tools and actions.

Prerequisites:

• Node.js (14.x or newer) and npm
• A Notion integration with the required permissions (read/write) and the Notion API token

Installation steps:

1. Install Node.js and npm from https://nodejs.org/
2. Install the MCP server package (locally in your project or globally):
   • Local project install: npm install notion-mcp-server
   • Global install (optional): npm install -g notion-mcp-server
3. Run the MCP server:
   • Using npx (recommended for quick start): npx -y notion-mcp-server
   • Or using a local install script within your project: ./node_modules/.bin/notion-mcp-server

Configuration:

• Provide environment variables for authentication and scope: NOTION_TOKEN: Your Notion API key (integration token) NOTION_PAGE_ID: The target Notion page or workspace ID as needed by your setup

Notes:

• If you’re running behind a client that injects environment variables, ensure NOTION_TOKEN and NOTION_PAGE_ID are visible to the MCP server process.
• The server will expose tools for pages, blocks, databases, comments, and user data as described in the documentation.

Tips and common considerations:

• Ensure your Notion integration has the necessary permissions (read/write) for the actions you intend to perform.
• Notion token and page/database identifiers should be kept secret and stored in a secure environment (e.g., env vars, secret manager).
• If you encounter rate limits or API errors, check your integration’s permissions and consider implementing request batching or retries in your client.
• The server supports multiple tools: notion_pages, notion_blocks, notion_database, notion_comments, and notion_users. Use the action field in each tool’s payload to select the specific operation (e.g., create_page, update_page_properties, query_database).
• If upgrading from an older version, review breaking changes in tool action names or payload schemas in the changelog.
• For debugging, enable verbose logs in your MCP client and watch the server logs for incoming payloads and Notion API responses.