概览
What is Notion MCP Server?
Notion MCP Server implements an MCP server for the Notion API, providing 22 tools that let AI agents read, create, update, and search Notion pages and data sources. It is designed for developers and users who want to connect their Notion workspace with MCP-compatible clients like Claude Desktop, Cursor, Zed, or GitHub Copilot.
How to use Notion MCP Server?
Create a Notion internal integration token, connect it to your pages/databases, then configure your MCP client with the server’s npm package or Docker image. Use NOTION_TOKEN or OPENAPI_MCP_HEADERS environment variables. The server runs via STDIO by default; optionally use --transport http for Streamable HTTP.
Key features of Notion MCP Server
- 22 tools covering pages, databases, data sources, and search
- Page content as Markdown for token-efficient AI editing
- Supports both STDIO and Streamable HTTP transport
- No code changes needed when upgrading tool names automatically
- Docker and npm installation methods
- Read-only token option for security‑conscious setups
Use cases of Notion MCP Server
- AI agents that read and write Notion pages in Markdown
- Automating data source queries with filters and sorts
- Moving pages between different parent locations
- Listing and retrieving templates from data sources
- Searching workspace pages and data sources
FAQ from Notion MCP Server
What is the difference between Notion MCP (remote) and this local server?
Notion MCP (remote) uses OAuth for easy installation and has tools optimized for AI agents. This local server requires a manual API token and may be sunset in the future; active support is only provided for the remote version.
Do I need to make any code changes when upgrading from v1.x to v2.0?
No. MCP tools are discovered automatically on server start. If you have hardcoded tool names (e.g., post-database-query), update them to the new names like query-data-source and change database_id to data_source_id.
What transport options are available?
The default is STDIO. You can also use Streamable HTTP by passing --transport http (optionally with --port, --host, and --auth-token). The HTTP endpoint is http://127.0.0.1:<port>/mcp.
How do I authenticate the server with Notion?
Set the NOTION_TOKEN environment variable to your integration secret. Alternatively, use OPENAPI_MCP_HEADERS with a JSON containing Authorization: Bearer ntn_**** and optionally Notion-Version.
What security considerations should I know?
The server limits write operations (e.g., cannot delete databases) but risk to workspace data exists from LLM exposure. You can create a read‑only integration token by granting only “Read content” access in the integration settings.
