Common Ninja MCP Server

A Model Context Protocol (MCP) server implementation for Common Ninja Widgets+, allowing AI assistants to interact with the Common Ninja API.

Prerequisites

• Node.js (v20 or higher)
• npm or yarn package manager
• Common Ninja Account Access Token (found in the Common Ninja dashboard)

Installation

npm install

Usage

The server runs in one of two transports:

• stdio (default) — single-tenant, for local desktop MCP clients (Claude Desktop, Cursor) launched via command/args. The token comes from COMMONNINJA_ACCOUNT_ACCESS_TOKEN.
• Streamable HTTP — multi-tenant/hosted, for remote MCP clients (ChatGPT, Claude, Cursor) and AI agents. Each request supplies its own token via the URL (/mcp/<TOKEN>) or a CN-API-Token header.

# stdio (local)
npm start

# HTTP (hosted) — any of these enable HTTP mode:
MCP_TRANSPORT=http npm start      # or: node build/index.js --http   (PORT defaults to 3000)

Hosted / HTTP mode (ChatGPT, Claude, Cursor, agents)

Once the server is deployed (anything that sets PORT, e.g. Render/Railway/Fly, runs HTTP mode automatically), connecting is one line. Grab your Account Access Token from the dashboard, then:

# Claude Code
claude mcp add --transport http commonninja https://mcp.commoninja.com/mcp/YOUR_API_TOKEN

Or point any MCP-compatible client at https://mcp.commoninja.com/mcp/YOUR_API_TOKEN. The token can also be sent as a CN-API-Token header instead of in the path. GET /healthz returns server status. (Stateless mode: only POST is served; GET/DELETE return 405.)

See DEPLOY.md for deploying the hosted server to Heroku at mcp.commoninja.com.

Zero-config login (OAuth)

When OAUTH_ENABLED=true, users connect with just the URL — no token to paste. The client discovers Common Ninja's authorization server and opens a browser login:

claude mcp add --transport http commonninja https://mcp.commoninja.com/mcp
# Claude opens a Common Ninja login + consent screen, then connects.

OAuth is opt-in and depends on a few authorization-server pieces (dynamic client registration, PKCE) landing in widgets-api. Until then, use the token methods above. Full design + turn-on checklist: OAUTH.md.

MCP Configuration Example (stdio)

{
  "globalShortcut": "",
  "mcpServers": {
    "commonninja": {
      "command": "node",
      "args": ["/path/to/commonninja-mcp-server/build/index.js"],
      "env": {
        "COMMONNINJA_ACCOUNT_ACCESS_TOKEN": "your_access_token_here"
      }
    }
  }
}

Get current path with process.cwd(), and use it as the path to the MCP server.

MCP Server

The MCP server is a Node.js application that listens for MCP connections from the Common Ninja desktop app.

Available MCP Server Tools

Widget Management

• commonninja_get_widget - Get widget data by ID
• commonninja_get_widget_schema - Get widget schema by type before updating widget data
• commonninja_get_widget_with_schema - Get a widget's current data AND its type schema in one call (prefer this before an update)
• commonninja_get_widget_integrations - Read a widget's integration config (integrations, notifications, email, payments) — read-only
• commonninja_update_widget - Merge current widget data with new partial widget data
• commonninja_update_widget_details - Rename a widget or update its description (widget-level metadata)
• commonninja_validate_json_schema - Validate widget data against a widget schema
• commonninja_list_widgets - List all widgets in the account with pagination
• commonninja_create_widget - Create a new widget with the specified type and data
• commonninja_delete_widget - Delete a widget by ID (permanent — confirm with the user first)
• commonninja_get_widget_types - Get a list of all available widget types
• commonninja_get_widget_editor_url - Get the editor URL for a widget
• commonninja_get_widget_embed_code - Get the embed code for a widget

Project Management

• commonninja_list_projects - List all projects with pagination
• commonninja_get_project - Get project details by ID

CRM Tools (Read-only)

• commonninja_project_list_contacts - List all project's contacts with pagination
• commonninja_project_get_contact - Get project's contact details by ID
• commonninja_project_list_submissions - List all project's submissions with pagination
• commonninja_project_get_submission - Get project's submission details by ID

Analytics

• commonninja_get_widget_analytics - Get analytics data for a specific widget

CLI (commonninja)

A token-cheap CLI for agents and automation — every command outputs structured JSON. Install from npm:

npm install -g @commonninja/cli
export COMMONNINJA_ACCOUNT_ACCESS_TOKEN="your_access_token_here"

commonninja help                  # list all commands
commonninja widget-types
commonninja widgets:list --limit 5
commonninja widget:create --type faq --name "My FAQ" --data @faq.json
commonninja widget:update <widgetId> --name "New name" --description "New description"
commonninja widget:embed <widgetId>

Or run without installing: npx @commonninja/cli widget-types. The MCP server bin is commonninja-mcp. Full reference: docs.commoninja.com/docs/reference/cli.

License

This project is licensed under the MIT License. See the LICENSE file for details.