mcp-notion-server
installs/mo · npmstarsforks
How to install mcp-notion-server?
suekou/mcp-notion-server
$git clone https://github.com/suekou/mcp-notion-serverAI-friendly MCP server for the Notion API. It helps agents find, read, query, and update Notion workspaces while keeping responses compact enough for day-to-day AI workflows.
README.md
| 1 | # Notion MCP Server |
| 2 | |
| 3 | AI-friendly MCP server for the Notion API. It helps agents find, read, query, and update Notion workspaces while keeping responses compact enough for day-to-day AI workflows. |
| 4 | |
| 5 | This server targets the Notion API `2026-03-11` and uses the current database/data source model. It exposes MCP tools, prompts, resources, structured tool results, and optional MCP Apps for interactive Notion workflows. |
| 6 | |
| 7 | ## Highlights |
| 8 | |
| 9 | - Search and target discovery with `notion_find`. |
| 10 | - Compact page reading with stable block IDs via `notion_read_page`. |
| 11 | - Data source schema inspection with `notion_inspect_data_source`. |
| 12 | - Schema-aware data source querying and item creation with simple values. |
| 13 | - Simple page editing tools for paragraphs, headings, lists, todos, quotes, callouts, code blocks, dividers, and safe Markdown append. |
| 14 | - Raw Notion API tools for advanced block, page, database, data source, comment, and user operations. |
| 15 | - Optional MCP Apps: Data Source Explorer and Page Workbench. |
| 16 | |
| 17 | ## Quick Start |
| 18 | |
| 19 | Add this server to an MCP host such as Claude Desktop: |
| 20 | |
| 21 | ```json |
| 22 | { |
| 23 | "mcpServers": { |
| 24 | "notion": { |
| 25 | "command": "npx", |
| 26 | "args": ["-y", "@suekou/mcp-notion-server"], |
| 27 | "env": { |
| 28 | "NOTION_API_TOKEN": "your-integration-token" |
| 29 | } |
| 30 | } |
| 31 | } |
| 32 | } |
| 33 | ``` |
| 34 | |
| 35 | Restart your MCP host after saving the configuration. |
| 36 | |
| 37 | ## Setup Guide |
| 38 | |
| 39 | ### 1. Create a Notion integration |
| 40 | |
| 41 | Open the [Notion integrations dashboard](https://www.notion.so/profile/integrations), then create a new internal integration. |
| 42 | |
| 43 |  |
| 44 |  |
| 45 | |
| 46 | ### 2. Configure capabilities |
| 47 | |
| 48 | Grant only the capabilities you need: |
| 49 | |
| 50 | - Read content: required for search, page reads, data source retrieval, and queries. |
| 51 | - Insert content: required for creating pages/items and appending blocks. |
| 52 | - Update content: required for updating pages, blocks, and data source schemas. |
| 53 | - Read comments / Insert comments: required only for comment tools. |
| 54 | - User information: required only when using user lookup tools. |
| 55 | |
| 56 | For full functionality during setup, enable read, insert, and update content. Add comment or user capabilities only if you plan to use those tools. |
| 57 | |
| 58 |  |
| 59 | |
| 60 | ### 3. Grant content access |
| 61 | |
| 62 | Open the **Content access** tab for your integration, then select the pages or databases you want the MCP server to read or edit. |
| 63 | |
| 64 | You can also grant access from the target Notion page or database: open the `...` menu, choose **Connections**, then add your integration. |
| 65 | |
| 66 | Notion only lets an integration access pages and databases that have been shared with it. A connection added to a page can also access that page's children. |
| 67 | |
| 68 |  |
| 69 | |
| 70 | ### 4. Copy the internal integration token |
| 71 | |
| 72 | Copy the integration secret. This value becomes `NOTION_API_TOKEN` in your MCP host config. |
| 73 | |
| 74 |  |
| 75 | |
| 76 | ### 5. Configure your MCP host |
| 77 | |
| 78 | For Cursor, Claude Desktop, and other MCP hosts, add this server config to your MCP settings: |
| 79 | |
| 80 | ```json |
| 81 | { |
| 82 | "mcpServers": { |
| 83 | "notion": { |
| 84 | "command": "npx", |
| 85 | "args": ["-y", "@suekou/mcp-notion-server"], |
| 86 | "env": { |
| 87 | "NOTION_API_TOKEN": "secret_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" |
| 88 | } |
| 89 | } |
| 90 | } |
| 91 | } |
| 92 | ``` |
| 93 | |
| 94 | For a locally built checkout: |
| 95 | |
| 96 | ```json |
| 97 | { |
| 98 | "mcpServers": { |
| 99 | "notion": { |
| 100 | "command": "node", |
| 101 | "args": ["/absolute/path/to/suekou-mcp-notion-server/build/index.js"], |
| 102 | "env": { |
| 103 | "NOTION_API_TOKEN": "secret_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" |
| 104 | } |
| 105 | } |
| 106 | } |
| 107 | } |
| 108 | ``` |
| 109 | |
| 110 | ## Recommended Workflow |
| 111 | |
| 112 | 1. Use `notion_find` to locate a page or data source. |
| 113 | 2. Use `notion_read_page` for page context and editable block IDs. |
| 114 | 3. Use `notion_inspect_data_source` before querying or creating data source items. |
| 115 | 4. Use `notion_query_data_source_by_values` and `notion_create_d |
People who liked this also viewed
6 picksType
- fastmcp🚀 The fast, Pythonic way to build MCP servers and clients.MCP ServersJul 2026
- playwright-mcpPlaywright MCP serverMCP ServersJul 2026
- ext-appsOfficial repo for spec & SDK of MCP Apps protocol - standard for UIs embedded AI chatbots, served by MCP serversMCP ServersJul 2026
- langchain-mcp-adaptersLangChain 🔌 MCPMCP ServersJul 2026
- mcporterCall MCPs via TypeScript, masquerading as simple TypeScript API. Or package them as cli.MCP ServersJul 2026
- mcp-proxyA bridge between Streamable HTTP and stdio MCP transportsMCP ServersJul 2026
