mcp-notion

This MCP server exposes the Notion API to your Claude/Desktop tooling via an MCP interface. It enables the LLM to retrieve pages, lists, and databases, update page properties, and manage blocks within a Notion workspace. To optimize token usage, the server can optionally convert responses to Markdown, reducing payload size for large Notion objects. Tools implemented include retrieving blocks and pages, appending or deleting blocks, updating page properties, creating databases, and querying or listing content. You can enable or disable specific tools using the enabledTools parameter in your client (for example, to restrict access to notion_retrieve_page, notion_update_page_properties, and notion_query_database). The server reads the NOTION_API_TOKEN from environment variables to authenticate with Notion’s API, so supply your integration token in NOTION_API_TOKEN before running.

Prerequisites:

• Node.js installed (recommended LTS version)
• Access to a Notion integration with a generated Internal Integration Token

1. Install dependencies and run via npx (recommended):

• Ensure you have the Notion integration token from Notion
• Run the MCP server via your preferred interface (Claude Desktop or CLI):
  • This example uses npx to install and run the server package: npx -y @suekou/mcp-notion-server
  • Set the environment variable with your Notion token: NOTION_API_TOKEN=your-integration-token

2. Alternative: Build and run locally with Node

• Install the package locally and start the server: NOTION_API_TOKEN=your-integration-token node path/to/server.js

3. Configure Claude Desktop (optional):

• Add or update claude_desktop_config.json with the Notion MCP server entry using either npx or node as shown in the config examples provided in the README.

4. Verify installation:

• Ensure the MCP server starts without errors and that authorized tools (like notion_retrieve_page, notion_update_page_properties, notion_query_database) respond correctly when invoked.

Tips and common considerations:

• Notion_MARKDOWN_CONVERSION is experimental. Enable it to reduce token usage when viewing content, but be aware it may affect editing capabilities due to formatting changes.
• Use the format parameter (json or markdown) per request to control response shape. Use markdown for human readability and json for programmatic processing.
• If you encounter permission issues, re-check that the Notion integration has the needed permissions and that it is invited to the relevant pages/databases.
• When enabling a subset of tools, specify them using --enabledTools to limit available commands to those you trust in a given session.
• If you modify the server locally, ensure you rebuild or restart the MCP server so changes take effect.
• Store tokens securely (avoid hardcoding in shared configs).