# suekou/mcp-notion-server: an MCP server that keeps Notion responses small enough for agents

> A TypeScript MCP server that wraps the Notion API 2026-03-11 data source model in compact read and write tools. It suits engineers wiring Notion into Claude Desktop, Cursor or another MCP host, and it stops being the right tool when you need API shapes its simplified tools do not cover.

**suekou/mcp-notion-server** — A Model Context Protocol server for connecting Notion to MCP-compatible clients

- Repository: https://github.com/suekou/mcp-notion-server
- Website: https://www.npmjs.com/package/@suekou/mcp-notion-server
- Stars: 919 · Forks: 179
- Language: TypeScript
- License: MIT
- Published: 2026-09-10 · Updated: 2026-09-10 · Language: en
- Canonical page: https://hysenlabs.com/projects/suekou-mcp-notion-server

## The problem: Notion API responses are too large for an agent's context

The Notion API returns block objects with full metadata. A single page read can produce a payload that crowds out everything else an agent is holding. The README frames this directly: the server helps agents find, read, query and update Notion workspaces "while keeping responses compact enough for day-to-day AI workflows."

That is the whole premise. This is not a general Notion SDK and it is not a sync tool. It is an MCP server, so its consumer is an MCP-compatible host, not your application code. If you are writing a Node service that talks to Notion, the official Notion client is the shorter path. This project exists for the case where a language model is the caller and the response has to survive a context window.

The second problem it addresses is targeting. Before an agent can read a page it has to know which page. notion_find handles discovery, and notion_inspect_data_source exists so the agent learns a data source's schema before it tries to write into it. Read the recommended workflow in order and that intent is visible: find, read, inspect, query or create, then edit.

## How the tools are layered, from notion_find down to raw JSON

The server exposes MCP tools, prompts, resources, structured tool results, and optional MCP Apps. The tool surface is deliberately tiered.

At the top are the simplified operations. notion_find locates pages and data sources. notion_read_page returns page context together with stable block IDs, which matters because editing a block requires its ID and IDs that shift between reads make multi-step edits unreliable. notion_inspect_data_source reports a data source's schema. notion_query_data_source_by_values and notion_create_data_source_item_from_values take simple values rather than raw property objects, which is the main ergonomic win: the agent supplies a value, the server maps it to the schema it just inspected. For edits there are notion_append_markdown, notion_append_content, notion_update_content and notion_update_content_batch, covering paragraphs, headings, lists, todos, quotes, callouts, code blocks and dividers.

Below that sit raw Notion API tools for advanced block, page, database, data source, comment and user operations. The README is explicit about when to use them: fall back to raw JSON tools only when the simplified tools do not cover the Notion API shape you need. That ordering is the design. The simplified layer is the default and the raw layer is the escape hatch, not the other way around.

The server targets Notion API 2026-03-11 and uses the current database/data source model. If your integration was written against the older database model, expect the data source concepts to be the vocabulary you work in here.

## Installing it and getting a first page read out of Claude Desktop

The package is published on npm as @suekou/mcp-notion-server and the README's quick start runs it through npx, so there is no global install step. You need a Notion internal integration first: create it in the Notion integrations dashboard, grant capabilities, and share the target pages or databases with it. Notion only lets an integration access pages and databases that have been shared with it, and a connection added to a page can also access that page's children.

Copy the integration secret, then add the server to your MCP host configuration. This is the README's example for Claude Desktop, Cursor and other hosts:

```json
{
  "mcpServers": {
    "notion": {
      "command": "npx",
      "args": ["-y", "@suekou/mcp-notion-server"],
      "env": {
        "NOTION_API_TOKEN": "secret_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
      }
    }
  }
}
```

Restart the MCP host after saving. If the server does not appear, the environment variable is the first thing to check, because a missing or wrong NOTION_API_TOKEN is the failure the config shape invites.

If you would rather run a local checkout, the README gives a node variant pointing at the built entry file:

```json
{
  "mcpServers": {
    "notion": {
      "command": "node",
      "args": ["/absolute/path/to/suekou-mcp-notion-server/build/index.js"],
      "env": {
        "NOTION_API_TOKEN": "secret_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
      }
    }
  }
}
```

Building that checkout requires Node.js 22 or newer and pnpm:

```bash
pnpm install --frozen-lockfile
pnpm run build
pnpm test
```

For a first real use, follow the README's ordering. Ask the host to run notion_find for the page you shared, then notion_read_page on the result. What you should see is page content with block IDs attached, and those IDs are what the update tools expect. If notion_find returns nothing, the integration almost certainly does not have access to that page yet.

## Capability scoping is the security boundary, and it is manual

The integration's capabilities are the real access control here. The README lists them: read content for search, page reads, data source retrieval and queries; insert content for creating pages and appending blocks; update content for updating pages, blocks and data source schemas; read and insert comments only for comment tools; user information only for user lookup tools.

That granularity is useful and easy to get wrong. The README suggests enabling read, insert and update content for full functionality during setup and adding comment or user capabilities only if you plan to use those tools. The practical consequence is that an agent with update content can rewrite blocks on every page the integration can see. There is no per-tool permission layer in the server itself, so the boundary is the Notion integration configuration plus the set of pages shared with it. If you want an agent that reads but never writes, grant read content and stop there.

The content access step is equally manual. You either select pages and databases from the integration's Content access tab or open the target page's menu, choose Connections and add the integration. Nothing is shared by default, which is the safe direction, but it also means a new page is invisible to the agent until someone shares it.

## Where it stops being the right tool

The simplified tools are a subset. The README says to fall back to raw JSON tools only when the simplified tools do not cover the Notion API shape you need, which is an admission that some shapes are not covered. If your workflow depends on those shapes, you are writing raw Notion API payloads through an MCP tool call, and at that point the server is a transport rather than an abstraction. An agent that has to construct raw block JSON is also more likely to get it wrong than one calling notion_append_markdown.

The API version is a second boundary. The server targets Notion API 2026-03-11 and the data source model. Anything you have that assumes the older database model needs translating, and the README does not document a compatibility mode.

There is also a version pin in the dependency list: @modelcontextprotocol/sdk is fixed at 1.29.0 rather than a range. That is a deliberate choice for reproducibility, but it means MCP SDK changes arrive only when the maintainer bumps that pin. The last push to the repository was on 2026-07-31, and the most recent release is v2.0.2 from 2026-06-22, so the project is not dormant, but you should not assume it tracks SDK releases immediately.

Finally, the README does not document rollback behaviour for the update tools. If notion_update_content_batch partially fails, the documentation does not say what state the page is left in. Treat batch edits as something to verify in Notion afterwards.

## Compared with the official Notion MCP server

Notion publishes its own MCP server, and the difference is in the response shape rather than the API coverage. The official server exposes the Notion API fairly directly, so a page read returns the API's block objects. This project's stated goal is the opposite: compact responses, stable block IDs, and schema-aware helpers that take simple values instead of raw property objects.

The trade is abstraction for fidelity. With this server, notion_inspect_data_source has to run before a write so the server can map your simple value onto the schema, which is an extra round trip the direct approach does not need. In exchange, the agent does not have to hold a full data source schema in context to write one row.

If you want the full API surface with no translation layer, the official server is the more predictable choice. If your constraint is context budget and you mostly do reads, appends and simple data source writes, this server's tool set is built around exactly that.

## Licence, build requirements and the cost of upgrading

The project is MIT licensed, which permits use, modification and distribution subject to the licence terms. The repository includes a LICENSE file. For anything beyond that summary, read the licence text rather than a description of it; this is not legal advice.

Upgrade cost is mostly the API version. A move to a new Notion API version or a further change to the database and data source model would touch the tools that map simple values onto schemas, because those mappings encode the model. The raw tools would be less affected since they pass payloads through.

On the build side, the engines field requires Node.js 22 or newer and pnpm 10.24.0 or newer, and the package manager is pinned to pnpm@10.24.0. Development commands are pnpm run build, pnpm test and pnpm run inspector for the MCP inspector. Linting and formatting run through Biome. If your environment is on an older Node LTS, the build will not run, though the npx path in an MCP host still depends on that host's Node version.

The optional MCP Apps, Data Source Explorer and Page Workbench, are documented separately in docs/mcp-apps.md, along with configuration and the full tool reference in docs/configuration.md and docs/tools.md.

## Conclusion

Adopt it if you run an MCP host, want Notion reads and writes to stay compact, and are willing to grant the integration only the capabilities you need. Skip it if you cannot share specific pages with an integration, or if your work depends on Notion API shapes the simplified tools do not model. Verify two things before rolling it out: that your host launches npx with the NOTION_API_TOKEN environment variable, and that notion_find returns the page or data source you expect in your own workspace.

## FAQ

### Is suekou/mcp-notion-server free?

The server is MIT licensed, so you can use, modify and distribute it under those terms. Notion's own plan and API access rules apply separately to the workspace you connect it to.

### Can ChatGPT be integrated with suekou/mcp-notion-server?

The README names Claude Desktop, Cursor and other MCP hosts as the configuration targets. It does not document ChatGPT as a supported host, so treat that as unconfirmed.

### Can Codex connect to suekou/mcp-notion-server?

The README only shows configuration for MCP hosts such as Claude Desktop and Cursor. Codex is not mentioned, so there is no documented setup for it.

## Sources

- [License: MIT](https://github.com/suekou/mcp-notion-server/blob/main/LICENSE)
- [Project website](https://www.npmjs.com/package/@suekou/mcp-notion-server)
- [README](https://github.com/suekou/mcp-notion-server/blob/main/README.md)
- [Releases](https://github.com/suekou/mcp-notion-server/releases)
- [suekou/mcp-notion-server on GitHub](https://github.com/suekou/mcp-notion-server)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/suekou-mcp-notion-server