Notion MCP (awkoy)
Notion MCP Server (awkoy)
Notion MCP on a token: an agent searches pages, runs databases, edits blocks and comments through three tools and 47 operations, with no manual sign-in
- 179 ★ on the repository
- Last commit
- MIT
Broad access
Why this level
- The agent creates, edits and archives pages, databases and comments on your behalf
- A personal token opens every page you can see, not a few chosen ones
Install
- Works in
Manual install
npx add-mcp notion-mcp-server --env NOTION_TOKEN=ntn_paste_your_token_hereThe add-mcp utility finds installed agents and writes settings for the ones you pick. Keep the `--env` flag: without it the entry has no token.
Access and checks
How we reviewBroad accessThe tool can change data, run commands or handle secrets.
- The agent creates, edits and archives pages, databases and comments on your behalf
- A personal token opens every page you can see, not a few chosen ones
This is third-party code. Review the repository files before installing.
What it does
Notion MCP by the author awkoy connects an agent to a Notion workspace with a token, with no sign-in to confirm in a browser. The server installs as the npm package `notion-mcp-server` and runs through `npx` over stdio. The `NOTION_TOKEN` variable holds either a personal token (`ntn_…`), in which case the agent sees everything you see, or an internal integration secret, in which case it sees only the pages you connected the integration to. Instead of one tool per API method the server exposes three: `notion_read` for reads, `notion_write` for writes and `notion_describe`, which returns the schema of a single operation with a working example on request. Behind them sit 47 operations: page search and editing, blocks, databases, data sources, database views, templates, comments, users and file uploads. A page can be read and rewritten as a whole in Markdown, and database row properties are written as plain values such as `Status: "Done"`: the server takes the types from the data source schema. Every write operation accepts a list of items. Up to 10 run in parallel, the `atomic` mode stops a batch at the first failure and tries to archive what was already created, and `idempotency_key` returns the earlier result for 5 minutes instead of writing twice. Requests to Notion go through a rate limiter, 3 per second by default, with a retry when the limit is hit.
Who it is for. For developers and teams who keep tasks, notes and knowledge bases in Notion and hand bulk edits of pages and databases to an agent in Claude Code, Cursor or Codex. It suits places where the agent runs without a person: CI, scheduled jobs, your own server.
Good fit when
- You need to rename or update dozens of pages in one batch, with a safe retry through an idempotency key
- An agent runs a task database: it selects rows by status and due date, creates new ones from a template and changes properties with plain values
- A specification page has to be read as Markdown, have its headings fixed and go back to Notion
- The agent starts in CI or on a schedule and cannot confirm a sign-in in a browser
- A file has to be attached to a page, or the model has to see an image from Notion, such as a screenshot on a bug report
Not a fit when
- You want a chat with Notion in the web version of claude.ai: the author points to Notion's own hosted connector for that
- You need support and guarantees from Notion: the code comes from a third-party author, not the company
- The machine has no Node.js 20 or newer: in Claude Desktop the `.mcpb` bundle avoids that, in other clients you need Docker
- An administrator turned off personal tokens, and nobody can connect an integration to every needed page one by one
Example request
Find every row in the Tasks database with the status In progress whose due date has passed and send me a list with page linksMCP
- Transport
- stdio, http
- Authentication
- API key
Environment variables
NOTION_TOKENrequired, secret- Notion personal token (ntn_…) or internal integration secret
NOTION_PAGE_ID- Default parent page for creating pages and databases
NOTION_READ_ONLY- The value true disables every write operation
NOTION_ALLOWED_OPERATIONS- Comma-separated allowlist of operations or groups
NOTION_UPLOAD_ROOT- Directory that path-based file uploads cannot leave
Limitations
- The server is unofficial: Notion has nothing to do with it.
- A personal token lasts a year from creation and opens every page available to you. A workspace administrator can turn such tokens off and revoke other people's.
- Rights are limited per operation, not per parameter: `update_page_markdown` can replace a page body, and blocking the `destructive` group does not disable it. Writes are switched off entirely with `NOTION_READ_ONLY=true` or `NOTION_ALLOWED_OPERATIONS=read`.
- The confirmation prompt before risky operations (`NOTION_CONFIRM_DESTRUCTIVE`) works only in clients that support confirmation requests; elsewhere the server answers `confirmation_unavailable`.
- The `upload_file` operation with a `path` source reads any file the server process can reach. Confine it with the `NOTION_UPLOAD_ROOT` variable.
- In HTTP mode anyone who reaches `/mcp` acts as the token owner, so outside a local address `MCP_AUTH_TOKEN` is required.
How to disable. Revoke the token at app.notion.com/developers/tokens with the Revoke button: access ends at once. Then remove the server from the agent's settings, in Claude Code with `claude mcp remove notion -s user`.
FAQ
How do I connect Notion MCP to Claude Code?
Get a token at app.notion.com/developers/tokens and run `claude mcp add notion -s user -e NOTION_TOKEN=ntn_paste_your_token_here -- npx -y notion-mcp-server`. For several clients at once the author offers `npx add-mcp notion-mcp-server --env NOTION_TOKEN=ntn_paste_your_token_here`: it finds installed agents and writes their settings. Without the `--env` flag the entry is created with no token, and the server answers every call with an auth error.
How is Notion MCP on a token different from Notion's hosted connector?
The hosted connector signs in through OAuth, and a person confirms the sign-in. This server works with a token, so it runs in CI, on a schedule and on your own server. For a chat in the web version of claude.ai the author recommends Notion's connector.
Which token should I pick, personal or internal integration?
The author recommends the personal token: it sees everything you see and does not need each page connected separately. An internal integration token sees only the pages you connected it to through the Connections menu. It is for cases where an administrator requires access per page. Most `object_not_found` errors come from an integration token that was never connected to the page.
How do I make Notion MCP read-only?
Set `NOTION_READ_ONLY=true` or `NOTION_ALLOWED_OPERATIONS=read`. Disabled operations disappear from the tool list, and when no write operation remains `notion_write` is not advertised at all. You can keep reads plus, for example, `append_blocks` and `add_page_comment`: `NOTION_ALLOWED_OPERATIONS=read,append_blocks,add_page_comment`.
How does the agent learn the parameters of one of 47 operations?
It calls `notion_describe` with the operation name and gets a JSON schema and a working example. If a call fails validation, the reply itself carries the schema, an example and a `fix` hint, so the request can be corrected in one step. Notion links can be used in page and block identifiers.
Can I run Notion MCP over HTTP on my own server?
Yes. Set `MCP_TRANSPORT=http` and the server serves `/mcp` on port 3000, on 127.0.0.1 by default. For any address other than local, set `MCP_AUTH_TOKEN`, otherwise anyone who reaches it gets access. There is an image `ghcr.io/awkoy/notion-mcp-server:latest`. The image starts in stdio mode by default and ships without a `HEALTHCHECK`.
Does the server work in Claude Desktop without Node.js?
Yes, through the `notion-mcp-server.mcpb` bundle from the latest release: open it with a double click or drag it into the extensions section of the settings and enter the token. For people who have never edited a config file, the docs folder holds a step-by-step walkthrough.
Discussion
No questions or reviews yet.
Related
MCP serversA Notion MCP server: the agent searches, reads, queries and updates workspace pages and databases
Official local MCP server for the Notion API: search, read and edit pages as Markdown, and work with databases
Official Anytype MCP server: an agent searches, creates and edits objects, lists and types in your knowledge base
Obsidian MCP Server
obsidian-mcp-server
An MCP server for an Obsidian vault: read, search and precisely edit notes, sections, frontmatter and tags
The official Notion plugin for Claude Code: four skills, ten slash commands and a connected MCP server in a single install
Trello MCP server with 57 tools: cards, lists, checklists, attachments, comments, custom fields and workspaces, plus acceptance-criteria extraction
Comparison with similar tools
Entries that share the main search query, and how they differ.
| Entry | Official | Authentication | Repository stars | Main difference |
|---|---|---|---|---|
| Notion MCP (awkoy) (this entry) | no | API key | 179 | |
| Notion MCP Server | yes | API key | 4,686 | Notion's official local server: rights are narrowed in the integration settings, and databases cannot be deleted through it |
| Notion MCP Server | no | API key | 925 | third-party server over stdio only, with separate editing tools for paragraphs, headings, lists and code blocks |
| AFFiNE MCP Server: AFFiNE notes and databases for agents | no | key is optional | 315 | an MCP server for AFFiNE |
README in short
The documentation covers getting a token, installing with one `add-mcp` command or by hand for Claude Code, Cursor, VS Code, Gemini CLI, Claude Desktop and Docker, tables of environment variables and operation groups for limiting rights. It separately describes HTTP mode with `MCP_AUTH_TOKEN`, file uploads and per-tool permissions for Claude Code. The repository holds a comparison with the official server, token-cost measurements in the `benchmarks` folder, a changelog, a migration guide from versions 1 and 2 and a step-by-step walkthrough for Claude Desktop.