MCP Integrations

CLI (npx socialcrm)

Install, authenticate, and auto-configure MCP for Cursor, Claude Code, and Gemini CLI.

Use the SocialCRM CLI to query brand data, check metrics, run workflows, and connect AI coding tools from your terminal. The CLI is a standalone Node.js package that communicates with the SocialCRM API over HTTP.

Install

npx socialcrm

Or install globally with your preferred package manager:

npm install -g socialcrm
# or
yarn global add socialcrm
# or
pnpm add -g socialcrm

Running socialcrm with no arguments shows an interactive menu with guided setup.

Requires Node.js 18+.

Configuration

The CLI needs your API key. Set it using one of these methods (checked in priority order):

  1. socialcrm auth (recommended):

    socialcrm auth sk_live_YOUR_KEY_HERE

    Saves to ~/.socialcrm/config.json (file permissions 600).

  2. Environment variable (recommended for CI/scripts):

    export SOCIALCRM_API_KEY=sk_live_YOUR_KEY_HERE

  3. Legacy RC file (~/.socialcrmrc) — auto-migrated to the new location on first use.

Get your API key at Settings > API Keys.

Quick Start

# Authenticate and set up your editor
socialcrm auth
socialcrm init

# List your brands
socialcrm brands list

# Check AI visibility metrics
socialcrm metrics "Ace Auto Repair"

# See recent mentions
socialcrm mentions "Ace Auto Repair" --platform chatgpt --limit 10

# Check credits and run a workflow
socialcrm credits
socialcrm workflows run ai_shop_checkup

# Get metric trend with sparkline
socialcrm trend "Ace Auto Repair" visibilityScore --days 14

Commands

Setup

socialcrm auth [api-key]               # Save API key (interactive if omitted)
socialcrm init                         # Auto-detect and configure editor
socialcrm init --cursor|--claude|--gemini|--all
socialcrm init --dir /path/to/project  # Specify project directory
socialcrm status                       # Check MCP server connection + list tools

Brands

socialcrm brands list                  # List all brand profiles
socialcrm brands get               # Get brand details (name or UUID)
socialcrm brands competitors       # List competitors for a brand

Mentions & Metrics

socialcrm mentions  [-p platform] [-l limit]
socialcrm metrics 
socialcrm monitoring 
socialcrm trend   [-d days]

Repository

socialcrm repo list  [-c category] [-l limit]
socialcrm repo search   [-l limit]

Workflows

socialcrm workflows list               # List available workflows + credit costs
socialcrm workflows run            # Run workflow (polls until complete)
socialcrm workflows run  --no-wait # Start and exit immediately
socialcrm workflows run  --context "Focus on local SEO"
socialcrm workflows status      # Check run status
socialcrm workflows runs [-s status] [-w workflowId] [-l limit]
socialcrm workflows cancel

Agents

socialcrm agents summary   # Agent run statistics

Credits

socialcrm credits                      # Show credit balance

Global Flags

Flag Description
--json Output raw JSON instead of formatted tables
--api-url <url> Override the API base URL
--help Show help for any command
--version Show CLI version

JSON Output

Every command supports --json for piping into jq or other tools:

# Get brands as JSON
socialcrm brands list --json

# Pipe to jq
socialcrm brands list --json | jq '.[].brandName'

# Use in scripts
BRAND_ID=$(socialcrm brands list --json | jq -r '.[0].id')
socialcrm metrics "$BRAND_ID" --json

Editor Configuration

socialcrm init writes the MCP server config for your AI coding tool:

Platform Config file
Cursor .cursor/mcp.json
Claude Code .mcp.json
Gemini CLI gemini-extension.json

Auto-detection checks for .cursor/ and .claude/ directories. Use explicit flags (--cursor, --claude, --gemini) to override.

Workflow Polling

By default, workflows run polls get_run_status every 5 seconds and shows a live spinner with per-agent progress. When the workflow completes, it prints the summary.

Use --no-wait to start the workflow and exit immediately — useful for CI or when you want to check status later with workflows status <runId>.

Error Handling

Errors print the error message and, when available, a hint with next steps:

Error: brandId is required
Hint: Call list_brand_profiles first to get available brand IDs, or pass the brand name directly.

Custom API URL

For development or self-hosted instances:

# Flag
socialcrm brands list --api-url http://localhost:3000/api/mcp-app

# Environment variable
export SOCIALCRM_API_URL=http://localhost:3000/api/mcp-app

# Config file
# Set serverUrl in ~/.socialcrm/config.json

Priority: --api-url flag > SOCIALCRM_API_URL env > config file > default (https://socialcrm.com/api/mcp-app).

Troubleshooting

socialcrm: command not found — If you installed globally, check Node.js is in your PATH and restart your terminal. Verify the global bin directory: npm config get prefix. If using npx, remember to prefix all commands: npx socialcrm brands list.

Authentication failed — Verify your API key is correct and hasn't been revoked. Regenerate at Settings > API Keys. Run socialcrm auth to re-authenticate.

Config file not created by init — Make sure you're in a project root directory. For Cursor, the .cursor directory must exist. For Claude Code, the project must be initialized. Try socialcrm init --cursor (or --claude, --gemini) explicitly.