Skip to content
Notion Arena

For AI agents

MCP server reference

notion-arena-mcp is a stdio MCP server that exposes the Notion Arena catalog as ten typed tools. It is read-only by default — listing, searching and building URLs never touches your Notion workspace. Only plan_install with a supplied token writes anything, and even then it prints the exact request sequence first.

Install

The package is published to npm as notion-arena-mcp. The legacy name blocksmith-mcp is kept as a bin alias for the first few releases so existing configs don't break.

Claude Code (recommended)

# Project scope — travels with the repo
claude mcp add --scope project notion-arena -- npx -y notion-arena-mcp

# Pinned to a specific version
claude mcp add --scope project notion-arena -- npx -y notion-arena-mcp@0.2.2

# Global (all your projects)
claude mcp add --scope user notion-arena -- npx -y notion-arena-mcp

Claude Desktop

Add the following entry to claude_desktop_config.json (~/Library/Application Support/Claude/ on macOS, %APPDATA%/Claude/ on Windows):

{
  "mcpServers": {
    "notion-arena": {
      "command": "npx",
      "args": ["-y", "notion-arena-mcp@0.2.2"],
      "env": {
        "NOTION_ARENA_SITE_URL": "https://notionarena.vercel.app"
      }
    }
  }
}

Cursor / Windsurf

Save the same JSON block to .cursor/mcp.json in your project root, or to Windsurf's MCP config panel. The schema is identical to Claude Desktop's.

Environment variables

  • NOTION_ARENA_SITE_URL — base URL of the site. Defaults to https://notionarena.vercel.app. Override this to point at a self-hosted deployment or a local dev server.
  • NOTION_ARENA_REGISTRY_URL — base URL of the JSON registry. Defaults to {SITE_URL}/r. Override only if you fork the registry separately.
  • BLOCKSMITH_SITE_URL / BLOCKSMITH_REGISTRY_URL — legacy aliases from the pre-rename package. Honoured as fallbacks so existing installs keep working.
Why stdio, not HTTP/SSE?
Stdio servers start on demand, leave no daemon running, and need no port. There is nothing to secure, no CORS to configure, and no locally-served URL to whitelist.

Tool reference

All tools take typed Zod parameters and return JSON. Errors are returned as structured { error: string } objects, never thrown exceptions.

Browsing

  • list_components({ category?, tier?, kind?, delivery?, capabilities? }) — returns every component matching the filters. Pagination is not needed: the full catalog is ~50 KB.
  • search_components("{query}") — case-insensitive substring search across name, tagline, description, features, use cases and tags.
  • get_categories() — eight categories with emoji, tint, blurb and current counts.
  • get_site_info() — version, total counts, endpoints, and any active rate limits.

Detail

  • get_component("{slug}") — full item: params, capabilities, features, use cases, delivery channels, and related slugs.
  • get_widget_schema("{slug}") — JSON Schema of every param (type, default, min/max, options, help text), ready to drive a config form or to coerce LLM output.
  • get_recipe("{slug}") — recipe-specific detail: declared manual steps, required Notion API scopes, and the sequence outline.

Building URLs & install plans

  • build_embed_url("{slug}", { config }) — returns { embedUrl, downloadUrl, htmlSnippet } with validated config. Unknown keys are dropped.
  • plan_install("{slug}", { mode: 'plan' | 'embed' | 'html-block' | 'api', config?, token?, parentPageId? }) — in plan mode, returns total request count, every payload, manual steps, and warnings, without touching your workspace. Add a token and parent page id to execute.
  • get_registry_item("{slug}") — raw shadcn registry JSON with file contents inlined, used by npx shadcn add.
  • get_install_guide("{slug}", "{mode}") — human-readable, Markdown-flavoured install instructions for the given channel.

What the server will not do

  • It will never call Notion without you passing a token, even in install mode.
  • It will never silently omit a manual step. Recipes declare every click-path the API cannot cover, and the plan prints them before executing.
  • It will not invent parameters. If a config key is not declared on the widget, it is dropped before the URL is built.
  • It will not phone home. The binary is open source; it fetches only the registry JSON and widget source files from the configured site URL.

Versioning & pinning

Widget source files are frozen per semver patch under /widgets/{slug}.html. Embed URLs serve the latest patch for the major.minor you requested, so bug fixes reach existing pages automatically. The MCP package follows semver and the npm version you pin is the tool schema you get.

To guarantee reproducible agent behaviour in CI, pin the package with npx -y notion-arena-mcp@0.2.2 rather than leaving the version floating.