Browse docs

Local MCP

The Post Notion MCP server runs locally over stdio. It's the documented, shipping path today — your agent launches it as a subprocess and talks to it directly.

Configuration

Command
node
Server file
~/.post-notion/post-notion-mcp.js
Transport
stdio
Auth
Device code (approved in the browser)
Config file
~/.post-notion/config.json

Install

Build the server once and install it to ~/.post-notion/. This copies the binary into place and registers the post-notion server with Claude Code; for other clients it prints the config to paste.

terminal
pnpm --filter post-notion-mcp build
pnpm --filter post-notion-mcp install:global

A published package is coming

Today the server installs from source. A one-line npx post-notion-mcp install lands with Remote MCP; the client config below won't change.

Then point your client at the installed server file:

Register the server, then run /mcp in a Claude Code session to confirm it connected.

terminal
claude mcp add post-notion --scope user \
  -- node ~/.post-notion/post-notion-mcp.js

Authenticate

Only the person who writes signs in; sharing a page needs no account. Auth is a device-code flow, cached after the first approval.

  1. 1In your agent, call health_check. If it returns needs_auth, call auth_status.
  2. 2auth_status returns a verificationUrl and a deviceCode. Open the URL, sign in to Post Notion, and approve access.
  3. 3Call complete_auth with the deviceCode. Your key is saved to ~/.post-notion/config.json.
  4. 4Call health_check again — it should report ok with the active endpoints.

Run logout to clear the cached key. health_check reports the active endpoints and where the credential came from, without printing the key itself.

Environment variables

Everything defaults to the hosted Post Notion deployment, so most setups need no environment at all. Override only to point at another deployment.

POST_NOTION_API_BASE
HTTP/API origin. Defaults to the hosted deployment.
POST_NOTION_CONVEX_URL
Convex query/mutation origin. Defaults to the hosted deployment.
POST_NOTION_API_KEY
Optional. Normally created by the auth flow and cached for you.
POST_NOTION_CONFIG_PATH
Optional. Alternate path for the config file.

Tools

The agent-facing surface, grouped by the loop. See MCP tools for each tool's parameters and schema.

Publishing

  • push_doc — publish or update a page and get its link
  • check_doc — lint HTML before publishing
  • list_versions — the version history of a page

Feedback

  • pull_threads · pull_comments — the review, as threads or raw comments
  • reply_comment · resolve_comment · set_status — answer and close the loop
  • pull_questionnaire_answers · pull_decisions — structured responses and decisions

Navigation

  • list_pages · create_page · move_page · delete_page — the page tree
  • list_docs · get_doc · delete_doc — documents
  • get_design_system · fetch_template — theming and templates

Account

  • health_check — endpoints and credential status
  • auth_status · complete_auth · logout — the auth flow
PreviousEmbedNextRemote MCP