mcp-notion-server
bysuekou· 1 MCP server
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.
How to install mcp-notion-server?
suekou/mcp-notion-server
$git clone https://github.com/suekou/mcp-notion-serverInstalls into the current project.
›Prefer a prompt? Paste this to your agent
Install mcp-notion-server by running `git clone https://github.com/suekou/mcp-notion-server`, then use it for the current task and follow its documentation at https://github.com/suekou/mcp-notion-server.
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 |
Related
6 picksType
- notion-mcp-serverOfficial MCP server for Notion APIJul 2026
- excel-mcp-serverExcel MCP Server for manipulating Excel filesApr 2026
- excel-mcp-server-masterA comprehensive Model Context Protocol (MCP) server for Excel file manipulationJun 2025
- excel-mcpA Model Context Protocol server for comprehensive Excel file manipulation using openpyxlOct 2025
- ms-365-mcp-serverA Model Context Protocol (MCP) server for interacting with Microsoft 365 and Office services through the Graph APIJul 2026
- mcp-google-sheetsThis MCP server integrates with your Google Drive and Google Sheets, to enable creating and modifying spreadsheets.May 2026
