Post Notion MCP

Post Notion MCP lets coding agents publish HTML docs to Post Notion, get a review URL, pull reviewer feedback, and push the next version to the same URL.

Install From npm

Use the public npm package in MCP clients:

npx -y @postnotion/mcp

Claude Code:

claude mcp add --scope user --transport stdio postnotion -- npx -y @postnotion/mcp

Manual MCP config:

{
  "command": "npx",
  "args": ["-y", "@postnotion/mcp"],
  "env": {
    "POSTNOTION_API_BASE": "https://postnotion.com",
    "POSTNOTION_CONVEX_URL": "https://rugged-hyena-579.convex.cloud"
  }
}

Fresh User Flow

1. Add the MCP server to your client.
2. In the agent, call health_check.
3. If health_check returns needs_auth, call auth_status.
4. Open the returned verificationUrl, sign in to Post Notion, and approve access.
5. Call complete_auth with the returned deviceCode.
6. Call health_check again.
7. Call list_projects.
8. Reuse a matching project, or call create_project.
9. Run check_doc on your HTML.
10. Call push_doc with project, slug, title, and mode.

After the user reviews the URL, call pull_threads or pull_comments, address the feedback, call resolve_comment or set_status, then call push_doc again with the same slug.

Claude Code From Source

From the repository root:

pnpm --filter @postnotion/mcp build
pnpm --filter @postnotion/mcp install:global

The installer copies the built server to ~/.postnotion/postnotion-mcp.js. If the Claude CLI is installed, it registers the postnotion MCP server. If not, it prints the JSON you can paste into another MCP client.

Source install manual config:

{
  "command": "node",
  "args": ["/Users/you/.postnotion/postnotion-mcp.js"],
  "env": {
    "POSTNOTION_API_BASE": "https://postnotion.com",
    "POSTNOTION_CONVEX_URL": "https://rugged-hyena-579.convex.cloud"
  }
}

health_check reports the active endpoints and credential source without printing the raw key.

Environment

• POSTNOTION_API_BASE: Post Notion HTTP/API origin. Defaults to https://postnotion.com.
• POSTNOTION_CONVEX_URL: Convex query/mutation origin. Defaults to the hosted Post Notion deployment.
• POSTNOTION_API_KEY or POSTNOTION_MCP_API_KEY: Optional. Normally created by auth_status plus complete_auth and saved in ~/.postnotion/config.json.
• POSTNOTION_CONFIG_PATH: Optional alternate config file path.

Legacy LOOP_API_BASE, LOOP_CONVEX_URL, LOOP_API_KEY, LOOP_MCP_API_KEY, and LOOP_CONFIG_PATH aliases are still accepted for existing source installs.

Optional Media Features

The core review loop does not require the local media pipeline. add_playable uses local audio tooling, and ink OCR uses @huggingface/transformers plus sharp. Run health_check with { "include_media": true } before using add_playable.