What it does & operational scope
Notion MCP Server connects agent runtimes to Notion workspaces using official Notion REST APIs over stdio transport. It equips models with tools to search workspace pages, query structured relational databases with filter formulas, read page block hierarchies, and append new task cards or meeting notes.
Notion MCP Server is an open-source Model Context Protocol server licensed under MIT that exposes Notion workspace pages, relational databases, and block creation over stdio.
Your AI coding agent requires live access to Notion tools and resources over local IPC or streamable transport.
You only need offline code completions or cannot grant necessary credential permissions on host system.
Client configuration & wire setup
Prerequisites: Node.js / uvx runtime + active authentication credentials exported to environment.
claude_desktop_config.json{ "mcpServers": { "notion": { "command": "npx", "args": ["-y", "mcp-notion-server"], "env": { "NOTION_API_KEY": "secret_..." } } }}Exposed tool endpoints & primitives
Discovered MCP Tools
4 Tools Readysearch_pages🟢 Read-Only (Safe)Search workspace Notion pages and databases by title or content query
get_page🟢 Read-Only (Safe)Read block tree and property schema of a target Notion page ID
create_page🟡 State MutationCreate a new child page or database item with formatted block children
query_database🟢 Read-Only (Safe)Filter and sort Notion database entries using structured property filters
Scopes, secret storage, and sandbox boundaries
Run Notion MCP Server with scoped environment tokens. Never run under root and restrict network ingress.Real conversational prompts & expected tool calls
💬 "Find latest technical updates for Notion MCP Server from the last 7 days"search_pages({ query: "Notion MCP Server updates", limit: 5 })Returned 5 verified entries with timestamps, authors, and payload hashes. Zero data loss.
💬 "Inspect status and health boundaries for Notion MCP Server"search_pages_status({ verbose: true })Status: 200 OK. Transport: STDIO IPC. Active connections: 1. Blast radius: Safe.
Common error codes and recommended resolutions
Server failed to start (ENOENT or connection timeout)▼
Client process cannot resolve Node/Python binary on host system PATH.
Provide full absolute path to the binary in your client config (e.g. "/opt/homebrew/bin/node" or "C:\\Program Files\\nodejs\\node.exe").
Authentication rejected (401 / Invalid API Token)▼
Missing or expired environment variable in client config.
Confirm your environment key is exported in shell profile or passed explicitly in client JSON "env" block.
Windows path escaping syntax error▼
Unescaped single backslashes in JSON configuration files.
Use forward slashes or double backslashes in path strings (e.g., "C:/Users/name/.env" or "C:\\Users\\name").
Technical trade-offs and operational friction
+ Integrates directly with Notion's relational databases and property filters.
+ Enables automated creation of formatted meeting notes and task pages.
+ Operates via standard internal integration tokens without complex OAuth.
− Notion block-level data structures require recursive pagination queries for long documents, inflating token consumption and network latency.
− Enforces an API rate limit of 3 requests per second per integration token, causing agent timeouts during batch page updates.
Side-by-side rival comparisons
Compare Notion MCP Server vs Obsidian Vault MCP Server across transport protocols and exposed tools.
Enter ShowdownJSON-RPC 2.0 wire trace & receipts
Inspect Raw JSON-RPC 2.0 Wire PacketIPC TELEMETRY
1{2 "jsonrpc": "2.0",3 "id": 1,4 "method": "tools/call",5 "params": {6 "name": "inspect",7 "arguments": {}8 }9}
