Notion Connector

[!NOTE] Status: prototype. First-cohort connectors are being written to validate the artifact shape against eval, installation and consumption from various agent harnesses. Treat nothing here as a stable contract. Pre-1.0 (0.x): breaking changes ship as a minor bump, features and fixes as a patch. Pin with a caret (^0.x.y) so you don't pick up a breaking minor automatically. Licensed under the Elastic License 2.0.

A growing catalog of agent-callable tools for the 9k+ apps Zapier integrates with. Each tool is simultaneously an agentskills.io-compliant skill artifact and an MCP Tool-shaped TypeScript module. The combined shape is the contribution: neither standard defines it alone.

The catalog is designed to run anywhere:

• as installable agentskills.io skills in any compatible client (Cursor, Claude Code, Codex, Copilot, VS Code, Gemini CLI, Goose, OpenCode, …)
• as native MCP tools registered into any MCP server's tools/list
• inside Zapier surfaces (Sidekick, the Zapier MCP server, code-based Zaps) — Zapier is the easy path, not the only path
• outside Zapier with user-held credentials via each connector's declared connectionResolvers

Using a connector

A connector is one folder, many surfaces — there are four ways to reach for it:

1. Install as an agentskills.io skill in a compatible AI client — Cursor, Claude Code, Codex, Copilot, Goose, and ~40 others. The agent reads SKILL.md and either (a) executes the connector's scripts directly when a task calls for it, or (b) uses the scripts + references/ as recipes when generating code.
2. Add as a dependency in your own TypeScript / Node code. Named imports give each script's wrapped .run(input, opts); the default import adds the structured object (scripts, connectionResolvers) for direct in-process calls. Pass auth as one [<resolver>:]<value> string: { connection: "env:NOTION_TOKEN" } (or { connections: { <slot>: ... } } for multi-slot scripts).
3. Call as a CLI — echo '{...}' | npx @zapier/notion-connector run <script> parses JSON on stdin/argv and prints the upstream API response. Cron, GitHub Actions, Terraform, anything that shells out.
4. Run as a local MCP server via the bundled CLI — npx @zapier/notion-connector mcp exposes every script as a native MCP tool over stdio, and the connector's SKILL.md + references/*.md as MCP resources, no consumer code required.

Each connector documents its own scripts, auth modes, and setup in its own README.md (e.g. apps/notion/README.md).

In your own code

import notion from "@zapier/notion-connector";

const result = await notion.scripts.search.run(
  { query: "Q4 planning" },
  { connection: "env:NOTION_TOKEN" },
);

// Or import one script's run function when you already know the name:
import { search } from "@zapier/notion-connector";
await search({ query: "Q4 planning" }, { connection: "env:NOTION_TOKEN" });

Auth is one [<resolver>:]<value> connection string per slot — env:NOTION_TOKEN reads the token from process.env.NOTION_TOKEN, zapier:<connection-id> routes through Zapier-managed auth, and a bare value is claimed by the first matching resolver.

Running a tool locally

This is what way 1 does under the hood, and — swapping node <script> for npx @zapier/notion-connector run <script> — also what way 3 (the CLI) does from the published package. Each script takes JSON on stdin or argv[1] and resolves auth from a --connection [<resolver>:]<value> flag against the connector's resolvers. The connection value is a selector (an env-var name or a connection id), not the secret itself, so it's safe to pass on argv; the env: resolver still reads the actual token from the named environment variable. Auth via a Zapier connection is the recommended path; direct mode is the fallback for callers who don't want a Zapier dep:

# With Zapier — Zapier connection UUID, auth handled by Zapier (recommended)
# Find a connection UUID with: zapier-sdk list-connections notion
echo '{"query":"foo"}' | node apps/notion/scripts/search.ts --connection zapier:<connection-id>

# Direct mode — your own 3P credentials (no Zapier needed); the token stays in env
echo '{"query":"foo"}' | NOTION_TOKEN=secret_xxx node apps/notion/scripts/search.ts --connection env:NOTION_TOKEN

# The `<resolver>:` prefix is optional — a bare value goes to the first resolver
# that claims it (a UUID → `zapier`, a set env-var name → `env`):
echo '{"query":"foo"}' | node apps/notion/scripts/search.ts --connection <connection-id>

# From the published package, `node <script>` becomes the bundled CLI (way 3) —
# same stdin/argv + `--connection` contract, no checkout needed:
echo '{"query":"foo"}' | npx @zapier/notion-connector run search --connection env:NOTION_TOKEN

# Run with `--help` to see each script's input schema and available resolvers:
node apps/notion/scripts/search.ts --help

The connector's SKILL.md describes the trade-offs between the two modes (setup steps, where the third-party credential lives, how revocation works).

Node (22.18+) runs the TypeScript directly — npm install the connector's deps first. Bun works too and auto-installs deps on first run.

Cloning the source

You don't need to clone the source code for a connector to use it; various options for installing and/or using a connector directly are explained above. However, if you do want the actual source instead — to read a script's code, browse references/, run a connector's tests, or hack on it — clone with a path filter so you only fetch the apps/<slug> folders you care about, not the whole catalog:

git clone --filter=blob:none --sparse https://github.com/zapier/connectors.git
cd connectors
git sparse-checkout set apps/notion apps/trello   # only the connectors you need

Each apps/<slug> is standalone-installable — no root npm install or workspace bootstrap is required. Just cd apps/<slug> && npm install.