Potencialize seu agente
O comando do próprio publicador. Não é um endpoint do PlugMCP.
Host a copy with our keys and logs.
npx -y [email protected]O Claude Code não tem link de instalação para um comando local. Copie o comando abaixo e execute-o em um terminal.
NOTION_TOKEN=<secret> NOTION_PAGE_ID=<value> claude mcp add io.github.awkoy-notion-mcp-server -- npx -y notion-mcp-server@3.4.0Execute em um terminal.
{ "mcpServers": { "io.github.awkoy-notion-mcp-server": { "command": "npx", "args": [ "-y", "[email protected]" ], "env": { "NOTION_TOKEN": "<secret>", "NOTION_PAGE_ID": "<value>" } } }}claude_desktop_config.json
URL remota ou um comando na sua máquina? Como as duas instalações diferem
Rodar no PlugMCP
A new server you create. It is not this listing's official endpoint. Use the publisher install when you want their URL and their credentials.
AbrirDo publicador
Give your AI read/write access to Notion with one token and one command. Claude Code, Claude Desktop, Cursor, VS Code, Cline, Zed, anything that speaks MCP: it can create pages, query databases, append blocks, apply templates, comment and upload files, in plain language.
Token-auth Notion MCP: pages, databases, blocks, comments, files. Runs headless in CI and agents.
Notion ships its own MCP server. Where this one differs:
id/type wrappers, annotations, and created_by/parent/icon blocks, and none of it reaches the model. That is the half that compounds, because a tool surface is paid once and responses are paid on every call. Measured against a reproducible fixture, with the caveats stated →Nothing is lost to get there: a database query returns flat name → value rows instead of Notion's raw properties bags (5.3× lighter in the benchmark), and verbose: true gives you the untouched SDK shape whenever you want it — within 4 tokens of what the official server returns, which is how the benchmark proves both are reading the same thing. Batched mutations with atomic rollback, idempotency keys, retry on rate limits and self-healing validation errors are built in, and the comparison below has the rest.
1. Get a Notion token. Open app.notion.com/developers/tokens → + New token → name it, pick your workspace → Create token → copy the ntn_… value. A Personal Access Token sees everything you can see, with no per-page sharing. (Page missing or empty? Your admin disabled PATs — see auth alternatives.)
2. Install it.
npx add-mcp notion-mcp-server --env NOTION_TOKEN=ntn_paste_your_token_here
add-mcp finds the MCP clients on your machine and writes the config for the ones you pick: Claude Code, Claude Desktop, Cursor, VS Code, Codex, Gemini CLI, Cline, Windsurf, Zed and a dozen others. Add -g to install at user level instead of the current project, -a claude-code to skip the picker, --all to write every client at once.
Keep the
--envflag. Without it the entry is written without a token, and the server starts and then fails every call with an auth error.
Any client that reads an mcpServers block (Cursor's ~/.cursor/mcp.json, Claude Desktop's claude_desktop_config.json, Cline's settings, Zed, Continue…):
{
"mcpServers": {
"notion": {
"command": "npx",
"args": ["-y", "notion-mcp-server"],
"env": { "NOTION_TOKEN": "ntn_paste_your_token_here" }
}
}
}
Claude Code:
claude mcp add notion -s user \
-e NOTION_TOKEN=ntn_paste_your_token_here \
-- npx -y notion-mcp-server
Claude Code speaks the 2025-era protocol over stdio unless told otherwise. Set MCP_PROTOCOL_NEGOTIATION=auto in its environment and it probes for MCP 2026-07-28 (stateless requests, cache hints on every list). The server serves both.
Cursor: 
— click, then replace YOUR_NOTION_TOKEN in the generated entry.
Gemini CLI:
gemini extensions install https://github.com/awkoy/notion-mcp-server
The repo ships a gemini-extension.json, so this installs as an extension: it asks for the token once, keeps it in your system keychain, and starts the server with npx.
Claude Desktop, without Node.js: download notion-mcp-server.mcpb from the latest release and double-click it (or drag it into Settings → Extensions), then paste your token when prompted. Never edited a config file before? The step-by-step walkthrough assumes nothing.
Docker / Podman / OrbStack:
claude mcp add notion -s user \
-e NOTION_TOKEN=ntn_paste_your_token_here \
-- docker run --rm -i -e NOTION_TOKEN ghcr.io/awkoy/notion-mcp-server:latest
The -i flag is required for stdio. The image is OCI-compliant, so Podman, OrbStack, colima, Rancher Desktop, Finch and nerdctl take the same flags. For a long-running HTTP container see Remote / HTTP transport.
3. Try it. In a new chat:
"Use Notion to make a page called 'Hello from my agent' and add a checklist of three things to try today."
Your AI calls notion_write and replies with a live page link.
where filters, flattened rowsget_page_markdown → edit → update_page_markdownget_image hands the model the picture itselfThe full catalog is the operations menu: 47 operations behind three tools.
To chat with your Notion in claude.ai's web UI, use Notion's hosted connector: it's one click. Use this server when the agent runs unattended, when context cost matters, or when you want batch and idempotent semantics and your own host.
What that buys you in practice: renaming 50 pages is one notion_write call with { items: [...], concurrency: 10 } rather than 50 trips through the agent's reasoning loop, and the prompt-token savings are the bigger half of the win. The benchmark has the method, the tokenizer, the control that validates it, an honest worst case, and the limits of its own sample.
Both go in the same NOTION_TOKEN env var; only where you get them differs.
💡 Most
object_not_founderrors are the wrong auth choice rather than a bug: an Internal Integration token that was never Connected to the page. Switch to a PAT.
Can: read every page you have access to; create and update pages and databases where you have edit rights; comment as you; upload files. Can't: reach pages you can't see, bypass workspace permissions, act as another user, or change admin settings. A PAT's scope is your account, so if you lose access to a page, so does the PAT. Issue separate tokens per teammate.
Expiry: PATs expire 1 year after creation (Notion docs). Set a reminder for month 11.
Revoking: app.notion.com/developers/tokens → Revoke next to the token, effective immediately. Workspace admins can revoke anyone's from Settings & members → Connections → All personal access tokens.
Admin disabled PATs? Ask them to enable it, or create an Internal Integration at app.notion.com/developers/connections (+ New connection) and • • • → Connect it to every page the agent should touch. Same NOTION_TOKEN env var.
Official reference: PAT guide · Authorization overview.
HTTP-transport variables (MCP_TRANSPORT, PORT, HOST, MCP_AUTH_TOKEN, …) are in Remote / HTTP transport.
Upgrading from v1.x or v2.x? Every env var still works unchanged. The break is the tool surface: v1's five tools, then v2's
notion_execute, becamenotion_read+notion_write, andnotion_describeis as it was. Modern clients rediscover tools automatically. Details in MIGRATION.md.
NOTION_ALLOWED_OPERATIONS (allowlist) and NOTION_BLOCKED_OPERATIONS (blocklist) each take a comma-separated list of group presets or exact operation names.
{ "env": { "NOTION_ALLOWED_OPERATIONS": "read" } } // read-only, the common case
{ "env": { "NOTION_BLOCKED_OPERATIONS": "destructive" } } // everything except removals
{ "env": { "NOTION_ALLOWED_OPERATIONS": "read,append_blocks,add_page_comment" } }
Names are case-insensitive, unknown tokens are ignored with a warning, the blocklist wins, and an allowlist that resolves to zero operations disables everything (fail-closed). Disabled operations vanish from the tools' operation enums, from notion_describe and from the notion://operations menu, so naming one fails validation before it runs; when no write operation is enabled, notion_write is not advertised at all. One line on stderr at startup says what resolved. Check it first when the config doesn't behave:
Operation access: 22/48 enabled (allow=read; block=(none))
Confirm instead of block. NOTION_CONFIRM_DESTRUCTIVE=true keeps destructive operations available and makes notion_write ask you before running one, through MCP elicitation: an elicitation/create request on 2025-era clients, an input_required round trip on MCP 2026-07-28 clients, where the retry carries a sealed requestState that only matches the call it was minted for. You get a yes/no dialog naming the operation and its target (the page, database, data source or block title when one retrieve can fetch it within 5 s, otherwise the id; for a batch, how many items).
Restores (restore_page, delete_database / delete_data_source with in_trash: false) and a batch_mixed_blocks call with no delete entry never prompt, and a blocked operation is still rejected with operation_not_allowed before anyone is asked. Decline, cancel or answer no and the call returns confirmation_declined; the server instructions tell the model not to retry and to ask you instead. A client that hasn't declared the elicitation capability gets confirmation_unavailable rather than a silent run. Use a client that supports elicitation, unset the variable, or block destructive operations outright.
† = also in the destructive group.
Limitations. Control is per-operation, not per-parameter: update_page_markdown is a write op that can replace a page body, and blocking destructive does not disable it. For a guaranteed no-mutation deployment use NOTION_ALLOWED_OPERATIONS=read or NOTION_READ_ONLY=true. MCP prompts may still mention disabled operations, but execution is rejected.
Uploads. upload_file takes its bytes as base64, a public url, or a local path the server reads directly. A path source can read any file the server process can, so when a model composes the path, set NOTION_UPLOAD_ROOT to confine it: relative paths resolve inside the root, and symlinks are resolved before the check so they cannot point out of it.
File URLs. Notion mints a fresh signed S3 URL for every hosted file on every read: about 1,650 characters (~500 tokens), valid for an hour, different each time, and easy for a small model to mangle. NOTION_FILE_URLS=ref replaces them in slim responses (get_page, search_pages, query_database, query_view, get_block, get_block_children, …) with short, stable refs.
Both resolvers re-read the object through the Notion API, so a ref stays valid as long as the file does. get_image fetches only the URL Notion returned for a Notion-hosted file, never one supplied by the caller, so it cannot be steered at a LAN host, a cloud metadata endpoint or an exfil target. External URLs (linked images, external files) are short and stable already: they pass through untouched in either mode, and get_image returns them as text rather than fetching them. get_page_markdown is Notion's own rendered markdown and is not rewritten. The default, full, leaves every response as it was.
The server speaks stdio by default. Set MCP_TRANSPORT=http to run it as a remote endpoint instead, for web clients, networked agents and shared deployments:
MCP_TRANSPORT=http PORT=3000 NOTION_TOKEN=ntn_xxx npx -y notion-mcp-server
# -> notion-mcp-server vX.Y.Z running on http://127.0.0.1:3000/mcp
It serves MCP Streamable HTTP on /mcp for both current protocol generations, picked per request from what the client sends. MCP 2026-07-28 clients get the stateless path, where every POST stands alone: no session, server/discover, cache hints on every list. 2024-11-05 … 2025-11-25 clients get sessions via the mcp-session-id header plus the GET stream and DELETE, and a GET/DELETE without a session id is answered 405. There is also an unauthenticated GET /health. The process is single-tenant: every request acts as the one NOTION_TOKEN it started with.
⚠️ Whoever reaches
/mcpacts as yourNOTION_TOKEN. On loopback, the default, that means local processes only. Before binding a non-loopbackHOST, setMCP_AUTH_TOKEN(the server warns if you don't) and put an authenticating reverse proxy in front of it.
Connecting from a client that supports headers (Claude Code, Cursor, VS Code), and checking it locally:
claude mcp add --transport http notion https://your-host/mcp \
--header "Authorization: Bearer <MCP_AUTH_TOKEN>"
curl http://127.0.0.1:3000/health
# -> {"status":"healthy","transport":"http","port":3000}
npx @modelcontextprotocol/inspector --transport http --server-url http://127.0.0.1:3000/mcp
In Docker, HOST=0.0.0.0 is what makes the published port reachable, since inside the container 127.0.0.1 is the container's own loopback. A non-loopback bind is exactly where MCP_AUTH_TOKEN earns its keep:
docker run --rm -e NOTION_TOKEN=ntn_xxx -e MCP_TRANSPORT=http -e HOST=0.0.0.0 -e MCP_AUTH_TOKEN=change-me \
-p 3000:3000 ghcr.io/awkoy/notion-mcp-server
Claude Desktop builds affected by anthropics/claude-code#93290 send a 2026-07-28 body under a
MCP-Protocol-Version: 2025-11-25header. The server realigns that one known mismatch so those builds work; every other header/body disagreement gets the rejection the spec prescribes (-32020).
The image ships without a HEALTHCHECK because it starts in stdio mode, where nothing listens and a built-in probe of /health would mark every stdio container unhealthy. Add one yourself for an HTTP deployment. The same command sits commented out in the Dockerfile, and works as --health-cmd on docker run too:
services:
notion-mcp-server:
image: ghcr.io/awkoy/notion-mcp-server:latest
environment:
NOTION_TOKEN: ${NOTION_TOKEN:?NOTION_TOKEN is required}
MCP_TRANSPORT: http
HOST: 0.0.0.0
MCP_AUTH_TOKEN: ${MCP_AUTH_TOKEN:?MCP_AUTH_TOKEN is required}
ports: ["3000:3000"]
healthcheck:
test: ["CMD", "node", "-e", "fetch('http://127.0.0.1:'+(process.env.PORT||3000)+'/health').then(r=>process.exit(r.ok?0:1)).catch(()=>process.exit(1))"]
interval: 30s
timeout: 3s
start_period: 5s
retries: 3
Three tools, whichever of the 47 operations you end up calling. notion_read runs the reads, notion_write the writes, and notion_describe returns one operation's JSON Schema plus a working example, which is worth a round-trip before a complex call: filter expressions, mixed block batches, database property definitions. Each tool's operation field is an enum of exactly what this server has enabled, so the menu ships with the tool list, a client can validate a call before sending it, and a name sent to the wrong tool fails in one round-trip with a message naming the right one.
Why the server exposes a few tools instead of one per endpoint: MCP Tool Design for AI Agents, Not API Endpoints.
Every id field (page_id, block_id, database_id, view_id, …) also accepts a Notion URL, so paste what Share → Copy link gives you. A block link's #fragment is used for block_id fields and a database link's ?v= for view_id fields.
// notion_read
{ "operation": "search_pages", "payload": { "query": "Q3 plan" } }
{ "operation": "get_page_markdown", "payload": { "page_id": "https://www.notion.so/Q3-plan-1f3c…" } }
// notion_write, single call
{ "operation": "set_page_title", "payload": { "page_id": "<page-id>", "title": "Q3 plan" } }
// notion_write, batch: every mutating op takes { items: [...], atomic?, concurrency?, idempotency_key? }
{
"operation": "set_page_title",
"payload": {
"items": [{ "page_id": "<p1>", "title": "First" }, { "page_id": "<p2>", "title": "Second" }],
"concurrency": 3,
"idempotency_key": "rename-pass-2026-07-02"
}
}
// markdown shortcut (create_page, append_blocks, update_block, update_page_markdown)
{
"operation": "create_page",
"payload": {
"parent": { "type": "page_id", "page_id": "<parent>" },
"title": "Notes",
"markdown": "# Heading\n\n- [ ] todo\n- [x] done\n\n```ts\nconst x = 1;\n```"
}
}
// a database row: plain property values, typed from the data source's schema
{
"operation": "create_page",
"payload": {
"parent": { "type": "data_source_id", "data_source_id": "<data-source-id>" },
"title": "Write the report",
"properties": { "Status": "In Progress", "Due Date": "2026-10-01", "Tags": ["q3", "docs"] }
}
}
// upload a file and place it on a page in one call
{
"operation": "upload_file",
"payload": {
"source": { "type": "path", "path": "~/Desktop/chart.png" },
"attach_to": { "block_id": "<page-or-block-id>", "caption": "Q3 revenue" }
}
}
A payload that doesn't validate comes back with the operation's full JSON Schema, a working example and a fix hint, so the next call can be corrected without a notion_describe round-trip.
MCP clients grant permission by tool name, so the read/write split lets you approve reads once and keep writes behind a prompt. In Claude Code (~/.claude/settings.json or the project's .claude/settings.json, where notion is whatever you named the server):
{
"permissions": {
"allow": ["mcp__notion__notion_read", "mcp__notion__notion_describe"]
}
}
Cursor's MCP settings offer the same per-tool allowlist. notion_read is annotated readOnlyHint: true and notion_write destructiveHint: true, for clients that read annotations.
Reads (get_*, list_*, search_pages, query_database, query_view) go through notion_read, everything else through notion_write.
The authoritative list, with batchability and the tool that runs each op, is served as an MCP resource at notion://operations.
Clients that support resource attachment (@-mention) can pull Notion content into context without a tool call. Dynamic resources route through the same auth, rate limiting and access gating as tool calls.
object_not_found / "Could not find …" — an Internal Integration token only sees pages explicitly Connected to it. Switch to a PAT to skip per-page sharing.NOTION_TOKEN in your client config, then that the token is still Active at app.notion.com/developers/tokens. Installed with add-mcp and skipped --env? The entry has no token; re-run with it.parent in the call, or set NOTION_PAGE_ID.multi_source_database from query_database or create_page — the database has several data sources. Call list_data_sources, then pass data_source_id (or a data_source_id parent) instead of database_id.warnings — the call ran; each entry names a field that was ignored (misspelt or misplaced) or a property name that was corrected. Fix the payload next time, nothing to retry.Cmd+Q, not window close) before reopening.-i flag is required: docker run --rm -i ….-e — write -e NOTION_TOKEN (forwards from the parent env) or -e NOTION_TOKEN=ntn_xxx, not -e NOTION_TOKEN ntn_xxx.Still stuck? GitHub Issues · FAQ · Notion API reference · MCP spec
The server runs on your machine or your own host and talks only to api.notion.com, over HTTPS, with the token you configure. No telemetry, no analytics, no server of ours in the path: nothing you read or write in Notion goes anywhere else. The token stays where your MCP client keeps it, in its config file or in a keychain for clients that have one. With HTTPS_PROXY set, traffic goes through your proxy instead. get_image fetches only the signed URLs Notion returns for files it hosts, never a URL supplied by the model, and upload_file reads a local file only when asked to, inside NOTION_UPLOAD_ROOT when that is set. Notion's own handling of your data is covered by Notion's privacy policy.
git clone https://github.com/awkoy/notion-mcp-server.git
cd notion-mcp-server
npm install
echo "NOTION_TOKEN=ntn_xxx" > .env
npm run build # tsc -> build/
npm test # vitest suite
npm run inspector # MCP inspector against the built binary
Point a client at the local build instead of npx:
claude mcp add notion -s user -e NOTION_TOKEN=ntn_xxx -- node "$(pwd)/build/index.js"
Logs go to stderr and are also sent to the client as MCP notifications/message entries (logger notion-mcp-server), so they show up in the client's own log view — VS Code's output channel, MCP Inspector, Claude Desktop's logs — where stderr is usually hidden. 2025-era clients pick the level with logging/setLevel (default info); MCP 2026-07-28 clients have no such call and ask per request with the io.modelcontextprotocol/logLevel envelope key, so a request without it gets no log notifications. Stderr is unaffected either way. At debug you also get one line per notion_read / notion_write call: operation, batch size, duration, ok or error, never the payload or page content.
@modelcontextprotocol/server + @modelcontextprotocol/node 2.0.0); stdio + Streamable HTTP transports; protocol revisions 2024-11-05 through 2026-07-28 (serveStdio / createMcpHandler for the stateless 2026-07-28 path, the sessionful transport for the rest)@notionhq/client@^5.22.0, pinned Notion-Version: 2026-03-11$defs deduplication for error envelopesremark / remark-gfmwithRetry with exponential backoff around every dispatched callverbose: true opt-outnpm test runs against a mocked Notion client. scripts/e2e.mjs drives the built server over stdio against a real workspace: every read operation, the resources and prompts, notion_describe for every operation, and, with --write, every write operation inside one throwaway page.
npm run build
printf 'NOTION_TOKEN=ntn_...\nNOTION_PAGE_ID=<page the token can write under>\n' > .env # gitignored
npm run e2e # read-only pass
npm run e2e -- --write # full pass; creates one page under NOTION_PAGE_ID and trashes it at the end
npm run e2e -- --write --keep # keep the test page for inspection
npm run e2e -- --modern # any of the above as an MCP 2026-07-28 client (stateless envelope, input_required confirmations)
It prints a PASS/FAIL table per check, lists any operation the run did not reach, and exits non-zero on failure. It is not part of CI.
PRs welcome. Fork → branch → commit → push → PR. Run npm test before submitting.
MIT — see LICENSE.
mcp-name: io.github.awkoy/notion-mcp-server
Token-auth Notion MCP: pages, databases, blocks, comments, files. Runs headless in CI and agents.
{ "mcpServers": { "io.github.awkoy-notion-mcp-server": { "command": "npx", "args": [ "-y", "[email protected]" ], "env": { "NOTION_TOKEN": "<secret>", "NOTION_PAGE_ID": "<value>" } } }}Ferramentas
Ainda não há lista de ferramentas. Servidores remotos recebem uma após a primeira verificação de saúde.
Perguntas frequentes
Copie nesta página a configuração stdio para Cursor, Claude Desktop, Claude Code ou VS Code. Ela usa a instalação do publicador, não um proxy do PlugMCP.
O publicador lista estas variáveis de ambiente: NOTION_TOKEN, NOTION_PAGE_ID.
Notion roda localmente via stdio.
Última verificação: 2026-11-15. Token-auth Notion MCP: pages, databases, blocks, comments, files. Runs headless in CI and agents.
