Skip to content
Back to search

mcp-notion-server

A Model Context Protocol server for connecting Notion to MCP-compatible clients

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/suekou--mcp-notion-server/badge.svg)](/listings/suekou--mcp-notion-server)

HTML

<a href="/listings/suekou--mcp-notion-server"><img src="/api/listings/suekou--mcp-notion-server/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

Add this server to an MCP host such as Claude Desktop:

{
  "mcpServers": {
    "notion": {
      "command": "npx",
      "args": ["-y", "@suekou/mcp-notion-server"],
      "env": {
        "NOTION_API_TOKEN": "your-integration-token"
      }
    }
  }
}

Restart your MCP host after saving the configuration.

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 146 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

  1. # Notion MCP Server
  2. 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.
  3. 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.
  4. ## Highlights
  5. - Search and target discovery with `notion_find`.
  6. - Compact page reading with stable block IDs via `notion_read_page`.
  7. - Data source schema inspection with `notion_inspect_data_source`.
  8. - Schema-aware data source querying and item creation with simple values.
  9. - Simple page editing tools for paragraphs, headings, lists, todos, quotes, callouts, code blocks, dividers, and safe Markdown append.
  10. - Raw Notion API tools for advanced block, page, database, data source, comment, and user operations.
  11. - Optional MCP Apps: Data Source Explorer and Page Workbench.
  12. ## Quick Start
  13. Add this server to an MCP host such as Claude Desktop:
  14. ```json
  15. {
  16. "mcpServers": {
  17. "notion": {
  18. "command": "npx",
  19. "args": ["-y", "@suekou/mcp-notion-server"],
  20. "env": {
  21. "NOTION_API_TOKEN": "your-integration-token"
  22. }
  23. }
  24. }
  25. }
  26. ```
  27. Restart your MCP host after saving the configuration.
  28. ## Setup Guide
  29. ### 1. Create a Notion integration
  30. Open the [Notion integrations dashboard](https://www.notion.so/profile/integrations), then create a new internal integration.
  31. ![Internal connections](docs/assets/setup/internal-connections.png)
  32. ![New connections](docs/assets/setup/new-connection.png)
  33. ### 2. Configure capabilities
  34. Grant only the capabilities you need:
  35. - Read content: required for search, page reads, data source retrieval, and queries.
  36. - Insert content: required for creating pages/items and appending blocks.
  37. - Update content: required for updating pages, blocks, and data source schemas.
  38. - Read comments / Insert comments: required only for comment tools.
  39. - User information: required only when using user lookup tools.
  40. For full functionality during setup, enable read, insert, and update content. Add comment or user capabilities only if you plan to use those tools.
  41. ![Notion integration capabilities](docs/assets/setup/capabilities.png)
  42. ### 3. Grant content access
  43. Open the **Content access** tab for your integration, then select the pages or databases you want the MCP server to read or edit.
  44. You can also grant access from the target Notion page or database: open the `...` menu, choose **Connections**, then add your integration.
  45. 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.
  46. ![Edit integration content access](docs/assets/setup/edit-connection.png)
  47. ### 4. Copy the internal integration token
  48. Copy the integration secret. This value becomes `NOTION_API_TOKEN` in your MCP host config.
  49. ![Copy internal integration token](docs/assets/setup/access-token.png)
  50. ### 5. Configure your MCP host
  51. For Cursor, Claude Desktop, and other MCP hosts, add this server config to your MCP settings:
  52. ```json
  53. {
  54. "mcpServers": {
  55. "notion": {
  56. "command": "npx",
  57. "args": ["-y", "@suekou/mcp-notion-server"],
  58. "env": {
  59. "NOTION_API_TOKEN": "secret_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
  60. }
  61. }
  62. }
  63. }
  64. ```
  65. For a locally built checkout:
  66. ```json
  67. {
  68. "mcpServers": {
  69. "notion": {
  70. "command": "node",
  71. "args": ["/absolute/path/to/suekou-mcp-notion-server/build/index.js"],
  72. "env": {
  73. "NOTION_API_TOKEN": "secret_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
  74. }
  75. }
  76. }
  77. }
  78. ```
  79. ## Recommended Workflow
  80. 1. Use `notion_find` to locate a page or data source.
  81. 2. Use `notion_read_page` for page context and editable block IDs.
  82. 3. Use `notion_inspect_data_source` before querying or creating data source items.
  83. 4. Use `notion_query_data_source_by_values` and `notion_create_data_source_item_from_values` for common data source work.
  84. 5. Use `notion_append_markdown`, `notion_append_content`, `notion_update_content`, or `notion_update_content_batch` for normal page edits.
  85. 6. Fall back to raw JSON tools only when the simplified tools do not cover the Notion API shape you need.
  86. ## For Developers
  87. These references are mainly for development, customization, and advanced MCP workflows:
  88. - [Configuration](docs/configuration.md): environment variables, command-line arguments, MCP host examples, development commands, and troubleshooting.
  89. - [Tools](docs/tools.md): complete tool reference grouped by workflow area.
  90. - [Workflows](docs/workflows.md): practical read, write, data source, migration, and error-handling guidance.
  91. - [MCP Apps](docs/mcp-apps.md): interactive Data Source Explorer and Page Workbench details.
  92. ## Development
  93. This project uses Node.js 22 or newer and pnpm.
  94. ```bash
  95. pnpm install --frozen-lockfile
  96. pnpm run build
  97. pnpm test
  98. ```
  99. Use the MCP inspector during local development:
  100. ```bash
  101. pnpm run inspector
  102. ```
  103. ## License
  104. This MCP server is licensed under the MIT License. This means you are free to use, modify, and distribute the software, subject to the terms and conditions of the MIT License. For more details, please see the LICENSE file in the project repository.

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.