Skip to content

About

One-shot Notion MCP OAuth authorization for ZCode — pages, databases, comments, chat session history and page versions via the official mcp.notion.com server

Resources

Stars

0 stars

Watchers

0 watching

Forks

Latest commit

 

History

1 Commit

Folders and files

Repository files navigation

zcode-notion-mcp

Authenticate the Notion MCP server for ZCode — including access to pages, databases, comments, page versions, and Notion chat session history — despite ZCode not being on Notion's client whitelist.

Same approach as DarkGenius/zcode-figma-mcp (built for Figma), with one improvement: this script bootstraps the discovery_state entry itself, so you don't need a preliminary ZCode restart just to seed the server id.

The problem

ZCode connects to remote MCP servers over HTTP and runs the standard MCP OAuth flow (RFC 9700 / StreamableHTTPClientTransport). Notion's MCP server (https://mcp.notion.com/mcp) only accepts a fixed list of client names, and "ZCode" isn't on it — so the out-of-the-box flow fails at client registration.

This script performs the OAuth flow under the client name Codex (which is accepted — verified against Notion's dynamic client registration endpoint), captures the resulting tokens, and injects them into ZCode's encrypted credential store so ZCode can use them directly on subsequent connections.

What it does

  1. Ensures a mcp:oauth:<id>:discovery_state entry exists for the Notion server — finds an existing one, or performs OAuth discovery itself (RFC 9728 /.well-known/oauth-protected-resource + RFC 8414 /.well-known/oauth-authorization-server) and creates the entry in the exact format ZCode expects.
  2. Registers a new OAuth client named Codex against the Notion MCP server.
  3. Opens a browser for you to log in to Notion, pick the pages to share, and authorize the request.
  4. Catches the localhost:3000/callback redirect and exchanges the authorization code for access + refresh tokens (PKCE, S256).
  5. Encrypts the tokens with the same AES-256-GCM scheme ZCode uses for ~/.zcode/v2/credentials.json, and writes them under the Notion server's id.
  6. Backs up credentials.json first and verifies the round-trip after writing.
  7. Verifies the connection by calling listTools() before exiting.

What you get

A successful run reports the tools the Notion MCP server exposes (72 at the time of writing), grouped roughly as:

Area Tools (examples)
Pages & documents notion-search, notion-fetch, notion-create-pages, notion-update-page, notion-move-pages, notion-duplicate-page
Databases notion-create-database, notion-query-data-sources, notion-query-multiple-data-sources, notion-update-data-source
Comments & discussions notion-create-comment, notion-get-comments, notion-set-discussion-resolved, notion-set-comment-reaction
Chat session history notion-search-sessions, notion-query-sessions, notion-read-session-event, notion-list-session-events, notion-spawn-session, notion-send-message-to-session
Page version history notion-get-version-changes, notion-view-version, notion-restore-version
Calendar & meetings notion-calendar-*, notion-create-meeting-note, notion-link-meeting-note-to-calendar-event
Files & attachments notion-create-file-upload, notion-download-attachment, notion-get-file-download-urls

Prerequisites

  • Node.js ≥ 20

  • ZCode installed and run at least once, with the Notion MCP server declared in ~/.zcode/cli/config.json:

    {
      "mcp": {
        "servers": {
          "notion": { "type": "http", "url": "https://mcp.notion.com/mcp" }
        }
      }
    }

Unlike the Figma script, a prior connection attempt is not required: if no discovery_state entry for the Notion URL exists yet, the script creates one.

Install

git clone https://github.com/Jommmain/zcode-notion-mcp
cd zcode-notion-mcp
npm install

Usage

# Default flow — opens the browser, waits for you to authorize in Notion.
node notion-mcp-auth.mjs

# Verbose mode — prints decrypted values for debugging.
node notion-mcp-auth.mjs --verbose

# Different client name (default "Codex").
node notion-mcp-auth.mjs --client-name "Claude Desktop"

# Custom MCP server URL (defaults to https://mcp.notion.com/mcp).
node notion-mcp-auth.mjs https://mcp.notion.com/mcp

After a successful run:

  1. Restart ZCode so it re-reads credentials.json.
  2. Verify in Settings → MCP that the notion server shows as connected and lists its tools.

Files written

Path Purpose
~/.zcode/v2/credentials.json The script adds/overwrites up to three keys here:
mcp:oauth:<server-id>:discovery_state (only if it didn't exist)
mcp:oauth:<server-id>:tokens
mcp:oauth:<server-id>:client_information
~/.zcode/v2/credentials.json.backup Copy of credentials.json from just before the first write of this run.

No other files are touched.

How server-id is resolved

The <server-id> in the credential keys is not derived from the URL — ZCode assigns it during OAuth metadata discovery and stores it inside the encrypted discovery_state payload. The script:

  1. Scans all mcp:oauth:*:discovery_state keys in credentials.json.
  2. Decrypts each one and matches resourceMetadata.resource against the target MCP URL.
  3. If nothing matches, runs the discovery itself (401 probe → resource metadata → authorization server metadata), generates a fresh id, and writes a discovery_state entry in the same format ZCode produces.

If ZCode has already attempted the Notion flow, its own entry is found and reused — no duplicate is created.

How encryption works

ZCode wraps credential values as enc:v1:<iv>.<authTag>.<ciphertext>, where:

  • algorithm: aes-256-gcm
  • key: sha256(ZCODE_CREDENTIAL_SECRET || fallback)
  • fallback: zcode-credential-fallback:<platform>:<homedir>:<username>
  • iv: 12 random bytes, auth tag: 16 bytes, all base64url-encoded

Set the ZCODE_CREDENTIAL_SECRET environment variable to override the fallback (e.g. on a shared/CI machine).

Token expiry & re-auth

Access tokens expire (see the expires_in field). When ZCode starts getting 401s from Notion, re-run the script and restart ZCode. The refresh token may extend the lifetime, but Notion eventually requires a fresh interactive authorization — including re-selecting the pages shared with the connection.

Troubleshooting

Safari can't connect to the server "localhost" after clicking Allow. The callback server binds to 0.0.0.0 so both IPv4 (127.0.0.1) and IPv6 (::1) work — the classic macOS fix, since Safari resolves localhost to ::1. If you still hit this, make sure nothing else is squatting on port 3000:

lsof -i :3000

Authorization succeeds, but ZCode gets 401 after restart. The machine profile (platform, homedir, username) used for key derivation must match the one ZCode runs under. If you run ZCode under a different user, set ZCODE_CREDENTIAL_SECRET consistently for both.

The script created a discovery_state but ZCode re-ran discovery itself. If ZCode assigned its own id after a reconnect, simply re-run this script — it will find ZCode's entry by URL and write the tokens under the correct id.

Notion shows fewer pages than expected. The integration only sees the pages you shared during authorization. In Notion: page → ··· → Connections → manage the MCP connection's page access, then re-run the script.

License

MIT

About

One-shot Notion MCP OAuth authorization for ZCode — pages, databases, comments, chat session history and page versions via the official mcp.notion.com server

Resources

Stars

0 stars

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages