mcp-notion

This MCP server acts as a bridge between Claude and Notion, exposing tools and resources that let you manage Notion pages, databases, and blocks through the Model Context Protocol. The server enables CRUD operations on databases and pages, block-level manipulations, and AI-assisted prompts such as summarize_notes, analyze_content, and suggest_tags. You can request lists of databases, create or update pages and databases, and append or modify blocks within a page, all while leveraging Notion metadata and content types. To start using it, run the MCP server via your preferred environment (as configured by your Claude Desktop integration), then invoke the listed tools through your MCP-enabled workflow. This setup is designed to be used in combination with Claude’s prompts and the Notion integration you provide, enabling seamless content creation, analysis, and organization within Notion. The available tools include: list_databases, create_database, query_database, update_database for databases; create_page, update_page, get_page, delete_page for pages; append_blocks, delete_blocks, get_blocks, update_blocks for blocks; and prompts like summarize_notes, analyze_content, and suggest_tags for content insights and tagging.

Prerequisites:

• Node.js 18 or higher
• A Notion API key / integration with appropriate permissions
• A Claude Desktop setup if you plan to connect via Claude

Installation steps:

1. Install Node.js if it’s not already installed: download from https://nodejs.org and install the LTS version.
2. Ensure you have access to the MCP server package:
   • This setup uses the MCP package published as @gabornyerges/mcp-notion-server.
3. Start the MCP server via npx (as configured in the example):
   • npx -y @gabornyerges/mcp-notion-server
4. Configure your Claude Desktop integration to point to the MCP server (see configuration example in the README).
5. In Claude Desktop, add the Notion API key as an environment variable for the MCP server if required by your setup (NOTION_API_KEY).
6. Verify the server is running by checking the console output and attempting a test call to list_databases or get_page using your MCP client.

Notes:

• If running locally, you can place the server configuration in claude_desktop_config.json as shown in the README.
• Ensure NOTION_API_KEY is kept secure and not committed to source control.

Tips and common issues:

• Environment variables: NOTION_API_KEY must be present for the server to access Notion data. Do not share this value publicly.
• If you encounter authentication errors, double-check the Notion integration permissions and the token scope.
• The MCP server communicates over stdio; use the MCP Inspector to debug tool invocations and payloads.
• Ensure the Notion integration has access to the required pages, databases, and blocks you intend to manage.
• When using create_page or update_page, provide proper title, properties, and content types to avoid schema validation errors.
• For block operations, remember that blocks are hierarchical; you may need to specify parent_page_id or database context when appending or updating blocks.
• If you upgrade the MCP server package, verify compatibility with your Claude Desktop version and any changes in the MCP API.