Notion Arena MCP Server

Notion Arena

---

🎯 What is Notion Arena?

Notion Arena is a machine-readable component registry for Notion — 203 pre-built components you can drop into any Notion page:

Notion is a trademark of Notion Labs Inc. This is an independent project and is not affiliated with or endorsed by Notion.

---

🎨 Popular Widgets Showcase

---

⚙️ Native Recipes (11)

---

🤖 For AI Agents — MCP + Skill

Plug Notion Arena directly into your AI agent — Claude Code, Cursor, Windsurf, Claude Desktop.

MCP Server

Gives your agent tools to list/search/configure/plan-install all 203 components:

# Claude Code (project scope)
claude mcp add --scope project notion-arena -- npx -y notion-arena-mcp

# Or pinned version
npx -y notion-arena-mcp@0.2.2

# Cursor — .cursor/mcp.json
# Claude Desktop — claude_desktop_config.json
# See docs/AGENT_SETUP.md for all clients

Skill

Teaches your agent the Notion Arena workflow, delivery channels, widget contract:

# Via skills.sh (Vercel) — cross-agent
npx skills add SynergyFlowLabs/notion-arena --skill notion-arena

# Via Claude Code plugin marketplace
/plugin marketplace add SynergyFlowLabs/notion-arena
/plugin install notion-arena@notion-arena-marketplace

# Manual
cp -r skills/notion-arena .claude/skills/notion-arena

Once both are installed, just ask:

"Find me a pomodoro timer for Notion" "Add a CRM pipeline to my Notion" "I need a habit tracker that works offline"

Your agent will use search_components, get_component, build_embed_url, plan_install automatically.

MCP Tools: list_components, search_components, get_component, get_widget_schema, build_embed_url, plan_install, get_registry_item, get_install_guide, get_categories, get_site_info

Skill: skills/notion-arena/SKILL.md + .claude/skills/notion-arena/SKILL.md + .claude-plugin/plugin.json + .claude-plugin/marketplace.json

See docs/AGENT_SETUP.md for MCP+Skill setup and docs/DEPLOY_AND_PUBLISH.md for free deployment (Vercel) + publishing MCP to npm & registry and Skill to skills.sh & plugin marketplace.

---

🏗️ Three Delivery Channels — Visualized

One HTML file serves both widget channels, so they cannot drift. Configuration comes from the query string on the hosted path and from a baked-in <script id="bk-config"> on the downloaded path, because a sandboxed block has no URL.

---

📋 Widget Contract — The 4 Rules

Every widget in public/widgets/ implements the same four rules. See /docs/authoring for the full guide and checklist.

Plus: body { overflow: hidden } with .wrap managing its own scroll (one scrollbar, not two), a prefers-reduced-motion escape hatch, and clipboard exports that always also console.log the payload as a fallback.

---

🏃 Running It Locally

# Install dependencies
npm install

# Restore 13 design/dev skills into .agents/skills/
npx skills experimental_install -y

# Start dev server
npm run dev          # http://localhost:3000

Requirements: Node 22+, Next.js 16 (Turbopack), React 19, Tailwind v4, TypeScript.

# Type-check
npx tsc --noEmit

# Widget contract checks (offline HTML validation)
npm run check:widgets

# Contrast audit
npm run audit:contrast

# Production build
npm run build

# MCP server
npm run generate:mcp-catalog  # 143 components → mcp/src/data/catalog.json
npm run build:mcp             # build notion-arena-mcp
npm run dev:mcp               # run MCP server with tsx (stdio)

Set NEXT_PUBLIC_SITE_URL in production to https://notionarena.vercel.app so registry manifests emit absolute URLs for the right host. Without it, URLs are derived from the request's forwarded host, falling back to https://notionarena.vercel.app (or http://localhost:3000 in local dev).

---

📁 Project Layout

public/widgets/*.html      the products: 192 self-contained HTML files
lib/catalog.ts             source of truth for all 203 components
lib/types.ts               component/param types + the 8 categories
lib/widget.ts              config coercion, injection, HTML rendering  (server)
lib/widget-url.ts          URL builders                                (browser-safe)
lib/notion/schema.ts       Notion API payload builders
lib/notion/installer.ts    executes plans against @notionhq/client
lib/recipes/               11 recipe declarations + planInstall()
lib/registry.ts            shadcn-compatible manifest generation
components/                site UI, catalog browser, configurator, docs prose
app/embed/[slug]/          framed, configured widget HTML
app/api/widget/[slug]/     the same HTML as a download
app/r/[name]/              registry: index.json, schema.json, {name}.json
app/api/install/           plan | embed | html-block | api
docs/RESEARCH.md           the research behind all of it
skills/notion-arena/       AI agent skill (workflow, channels, contract)
mcp/                       MCP server (tools for agents)

---

📦 The Registry (shadcn-compatible)

GET /r/index.json          the whole catalog
GET /r/{name}.json         one item, HTML or recipe JSON inline
GET /r/schema.json         JSON Schema of every widget's parameters

// mcp config / components.json
{ "registries": { "@notion-arena": "https://notionarena.vercel.app/r/{name}.json" } }

# see exactly what an install will do: no credentials, touches nothing
curl -X POST localhost:3000/api/install \
  -H 'content-type: application/json' \
  -d '{"component":"crm-pipeline","mode":"plan"}'

# then run it
curl -X POST localhost:3000/api/install \
  -H 'content-type: application/json' \
  -d '{"component":"crm-pipeline","mode":"api",
       "token":"'"$NOTION_TOKEN"'","parentPageId":"'"$PAGE_ID"'"}'

mode: "plan" requiring no token is deliberate: review the request sequence before authorising any write to your workspace.

---

⚠️ Two Things Worth Knowing

A widget cannot read or write your Notion data. Notion's HTML block sandbox has no network access and no bridge to its parent page. Widgets may keep user-entered personal state in this browser, but that state is not Notion data and is not shared. If a workflow needs workspace records, collaboration, permissions, or an audit trail, use a native database or recipe.

Relations force a two-pass install. Since Notion split databases from data sources, a relation property targets a data_source_id that does not exist until the target database has been created and read back. planInstall() therefore emits: create databases with base properties → read back each data source id → patch in relations → patch in rollups → patch in formulas → views → seed rows → pages → block bodies in chunks of 100.

Recipes also declare what they cannot do. Four real API gaps (no button block type, no automation endpoint, no recurring-template endpoint, no synced-block duplicates) appear as manual[] steps, each citing the limitation. A manual step whose reason is "it's easier by hand" is rejected.

---

🤝 Contributing

We welcome contributions! Whether it's a new widget, a native recipe, a bug fix, documentation, or an idea — here's how to contribute.

Quick Start for Contributors

1. Open an Issue — Discuss your idea first. Check for duplicates. Get maintainer feedback.
2. Fork & Clone — Create your branch: git checkout -b feat/my-widget
3. Develop — Follow the widget contract (see checklist below)
4. Test — Run all checks locally
5. Pull Request — Clear title, link issue, screenshots/GIFs, update CHANGELOG
6. Review — Maintainer review, CI checks, widget contract audit
7. Merge — Auto-deploy to Vercel, MCP catalog regenerates, available immediately

Widget Authoring Checklist

Every widget must pass all checks before merge — see scripts/check-widgets.mjs.

Adding a New Widget

1. Create public/widgets/my-widget.html (single HTML file, self-contained)
2. Add entry to lib/catalog.ts with all required fields:

   {
     slug: "my-widget",
     name: "My Widget",
     emoji: "🎯",
     tagline: "One-line hook",
     description: "Full paragraph explaining what it does and why.",
     category: "time", // time | dashboards | trackers | planning | business | docs | visuals | automations
     kind: "widget",
     tier: "free", // free | pro
     tags: ["tag1", "tag2"],
     color: "blue", // red | orange | yellow | green | blue | purple | pink | brown | gray
     params: [
       { key: "param1", label: "Label", type: "number", default: 10, min: 1, max: 100 },
       { key: "theme", label: "Theme", type: "select", default: "auto", options: [...] },
       { key: "accent", label: "Accent", type: "color", default: "#2383e2" },
     ],
     features: ["Feature 1", "Feature 2"],
     useCases: ["Use case 1", "Use case 2"],
     capabilities: {
       interactive: true,
       offlineSafe: true,
       persistsLocally: false,
       writesToNotion: false,
       needsNetwork: false,
     },
   }
   

3. Run npm run check:widgets and npm run typecheck
4. Test in Notion (embed + HTML block)
5. Submit PR

Adding a Native Recipe

1. Create recipe in lib/recipes/my-recipe.ts exporting planInstall() and schema
2. Add entry to lib/catalog.ts with kind: "native" and recipe: "my-recipe"
3. Run npm run generate:mcp-catalog and npm run build:mcp
4. Test with mode: "plan" then mode: "api"
5. Submit PR

Code Style

• TypeScript strict mode — no any, explicit types
• Tailwind v4 — utility-first, no custom CSS unless necessary
• React 19 — server components by default, 'use client' only when needed
• Conventional Commits — feat:, fix:, docs:, chore:, refactor:

---

📜 Honesty Policy

• No fabricated install counts, star counts, or customer logos
• Badges are qualitative (new, popular, staff-pick) and derived from the catalog
• Market numbers appear only where cited
• Capability claims are booleans in the catalog (interactive, offlineSafe, persistsLocally, writesToNotion, needsNetwork) exposed in the registry so an agent can filter on them instead of reading prose

---

📄 License

MIT License — see LICENSE for details.

Components you download are yours: modify them, host them, ship them in templates you sell. Free components carry no attribution requirement. See /legal/terms.

---

🔗 Links

• Live Site: https://notionarena.vercel.app
• MCP Package: https://www.npmjs.com/package/notion-arena-mcp
• MCP Registry: https://registry.modelcontextprotocol.io
• Documentation: https://notionarena.vercel.app/docs
• Research: docs/RESEARCH.md
• Agent Setup: docs/AGENT_SETUP.md
• Deploy & Publish: docs/DEPLOY_AND_PUBLISH.md
• Contributing: CONTRIBUTING.md
• Changelog: CHANGELOG.md

---