suekou/mcp-notion-server: a compact Notion bridge for MCP clients
A Model Context Protocol server for connecting Notion to MCP-compatible clients
At a glance
- What is it?
- The server wraps the Notion API 2026-03-11 in tools that return small, structured results for AI agents. The simplified tools are its main value, and the raw passthrough tools are the escape hatch when a Notion shape does not fit.
- Who is it for?
- Adopt it if your MCP client needs to read and edit selected Notion pages without dumping large JSON into the model context, and if you are willing to run Node.js 22 or newer through npx. Skip it if your integration cannot be granted access to the specific pages and data sources you need, because Notion restricts an integration to content shared with it.
- Can I use it commercially?
- Yes. MIT is a permissive licence: you can use, modify and sell software built on it, as long as you keep its copyright and licence notices.
- Is it still maintained?
- Yes. The repository last received commits 47 days ago.
- What is it written in?
- Mainly TypeScript, according to GitHub's language statistics.
Answers come from the project's GitHub data, last synced on September 15, 2026, and from our analysis. They are not legal advice.
DEEP OPEN-SOURCE ANALYSIS
What the server is for
Notion's API returns block trees, property objects and pagination envelopes that are verbose relative to what an agent usually needs. The README states the server exists to help agents find, read, query and update Notion workspaces while keeping responses compact enough for day-to-day AI workflows. That framing is the whole pitch. The target user is someone running an MCP-compatible host (the README names Claude Desktop and Cursor as examples) who wants the model to work with Notion pages and data sources without pasting raw API payloads into the conversation. The server itself is TypeScript, published to npm as @suekou/mcp-notion-server, and licensed under MIT.
The tool surface, split into simplified and raw
The README divides the tool set into two layers. The simplified layer starts with notion_find for search and target discovery, then notion_read_page for page reading that returns stable block IDs, notion_inspect_data_source for schema inspection, and notion_query_data_source_by_values plus notion_create_data_source_item_from_values for data source work with simple values. Page editing is covered by notion_append_markdown, notion_append_content, notion_update_content and notion_update_content_batch, with support listed for paragraphs, headings, lists, todos, quotes, callouts, code blocks and dividers. The second layer is a set of raw Notion API tools for advanced block, page, database, data source, comment and user operations. The README's recommended workflow is explicit about the order: find, read, inspect the data source, then use the value-based tools, and fall back to raw JSON tools only when the simplified tools do not cover the Notion API shape you need. That ordering matters because the simplified tools are schema-aware, so notion_inspect_data_source is the step that tells the agent what a data source expects before it tries to query or create an item.
Getting it into an MCP host
The quickest path is the npx form the README gives: an mcpServers entry named notion, command npx, args ["-y", "@suekou/mcp-notion-server"], and an env block containing NOTION_API_TOKEN. The README notes you should restart the MCP host after saving the configuration. For a locally built checkout, the same entry uses command node and args pointing at the absolute path to build/index.js, again with NOTION_API_TOKEN in env. The token comes from a Notion internal integration created in the integrations dashboard. Capability checkboxes on that integration are not cosmetic: read content is required for search, page reads, data source retrieval and queries; insert content for creating pages or items and appending blocks; update content for updating pages, blocks and data source schemas; comment capabilities only for comment tools; user information only for user lookup tools. The README suggests enabling read, insert and update during setup and adding the other two only if you plan to use those tools. Content access is a separate step: the integration sees only pages and databases explicitly shared with it, and a connection added to a page can also reach that page's children.
Where the design gets awkward
Two constraints stand out. First, the server targets Notion API 2026-03-11 and the current database/data source model. If your workspace or tooling still assumes the older database-centric shapes, the simplified tools will not line up, and you will be living in the raw JSON tools, which defeats the reason to pick this server. Second, the access model is inherited from Notion, not invented here: an integration only reaches content shared with it. A token that works in one workspace will return empty results or errors in another until someone opens the target page, goes to the Connections menu and adds the integration. That is a per-page or per-database manual step, and it is the most common way a first run looks broken. There is also a capability mismatch risk: if you enable only read content but the agent calls notion_append_markdown, the failure surfaces at the Notion API, not at configuration time.
MCP Apps and the docs directory
The README mentions optional MCP Apps, a Data Source Explorer and a Page Workbench, described as interactive Notion workflows, with details deferred to docs/mcp-apps.md. Because the material does not describe how those apps are launched or whether they require a host that supports the MCP Apps extension, treat them as optional and verify against that file before relying on them. The rest of the documentation is split across docs/configuration.md for environment variables, command-line arguments, host examples, development commands and troubleshooting, docs/tools.md for the complete tool reference grouped by workflow area, and docs/workflows.md for read, write, data source, migration and error-handling guidance. The README's own Recommended Workflow section is a summary of the last of those.
A different approach: the official Notion MCP server
Notion publishes its own MCP server, and the practical difference is scope and control. The official server is maintained by Notion and tracks their API directly, so it is the safer default if you want the vendor's own tool definitions and do not need a curated, compact subset. This project takes the opposite stance: it curates. The simplified tools accept simple values and inspect schemas first, which is a deliberate reduction of the API surface aimed at keeping model context small, and it keeps the raw tools underneath so nothing is truly out of reach. If your workflow is mostly reading pages and appending Markdown into a handful of shared documents, the curated layer is the reason to choose this server. If you need exhaustive coverage of every Notion endpoint with vendor backing, the official server is the more direct route.
Building from source and what maintenance looks like
The README lists Node.js 22 or newer and pnpm as the development requirements, with pnpm install --frozen-lockfile, pnpm run build and pnpm test as the three commands, plus pnpm run inspector for the MCP inspector during local development. The frozen lockfile flag means the build expects the committed pnpm-lock.yaml to match package.json, so a dependency bump without a lockfile update will fail the install rather than silently resolve. Release cadence visible in the repository metadata is three versions in roughly seven weeks (v2.0.0 in May, then v2.0.1 and v2.0.2 on the same day in June), which suggests the maintainer ships fixes quickly but also that minor versions can move. Pinning the version in your mcpServers args instead of relying on npx to fetch latest is the low-effort way to avoid a surprise. On licensing, the MIT License permits use, modification and distribution subject to its terms; that is a permissive arrangement, but the file itself is the authority, not this summary.
Editorial conclusion
Adopt it if your MCP client needs to read and edit selected Notion pages without dumping large JSON into the model context, and if you are willing to run Node.js 22 or newer through npx. Skip it if your integration cannot be granted access to the specific pages and data sources you need, because Notion restricts an integration to content shared with it. Before wiring it into a host, verify that your workspace is on the Notion API version 2026-03-11 data source model, that the token is stored as NOTION_API_TOKEN, and that the tools you plan to use match the capabilities you enabled on the integration.
Community notes