@socialneuron/mcp-server

96 MCP tools for AI-powered social media management — 94 exposed over the remote MCP endpoint and REST API (2 screen-capture tools run locally over stdio). Query /.well-known/mcp/server-card.json for the live count.

Contents

• Compatibility
• Integration Methods
• Platform Status
• Quick Start
• What You Can Do
• Tool Categories
• Authentication
• Pricing
• Scopes
• CLI Reference
• Automation Flow
• Security
• Telemetry
• Examples
• Documentation

Compatibility

Every release is published from GitHub Actions with npm provenance attestation (SLSA Build L2 via OIDC Trusted Publishing) — verify with npm view @socialneuron/mcp-server --json | jq .dist.attestations.

Integration Methods

All methods share the same tool catalog, auth, scopes, and credit system. Compare methods.

Platform Status

The hosted endpoint and REST API track the live matrix; check socialneuron.com/integrations for current availability.

What You Can Do

Ask Claude things like:

• "Generate 5 content ideas about sustainable fashion for Gen Z"
• "Create a 30-second video ad for my product launch"
• "Schedule this video to YouTube and TikTok at 9am tomorrow"
• "Show me my best-performing content this month"
• "What are the trending topics in my niche right now?"
• "Check my analytics and suggest improvements"
• "Set up autopilot to post 3 times per week"

Tool Categories (96 tools)

Full machine-readable listing in tools.lock.json (sealed manifest, verified in CI).

94 hosted tools are accessible via MCP and REST API (POST /v1/tools/{name}); the 2 screen-capture tools run locally over stdio.

Content Lifecycle

Management & Optimization

Utilities

Authentication

Three auth methods, in order of recommendation:

Device Code (Recommended)

npx -y @socialneuron/mcp-server login --device

Opens browser, you approve, CLI receives API key automatically.

Browser Flow

npx -y @socialneuron/mcp-server login

Browser-based OAuth flow.

API Key Paste

npx -y @socialneuron/mcp-server login --paste

Generate a key at socialneuron.com/settings/developer, paste it in.

Keys are stored in your OS keychain (macOS Keychain, Linux secret-tool) or file fallback.

Windows users: The file fallback (~/.config/social-neuron/credentials.json) does not have strong permission enforcement on NTFS. For production use on Windows, set the SOCIALNEURON_API_KEY environment variable instead.

Pricing

MCP access requires a Pro plan or higher:

Sign up at socialneuron.com/pricing.

Scopes

Each API key inherits scopes from your plan. Tools require specific scopes to execute.

CLI Reference

These commands run directly in your terminal — no AI agent needed. Useful for scripts, CI/CD, and quick checks.

After global install (npm i -g @socialneuron/mcp-server), use socialneuron-mcp directly. Otherwise, prefix with npx @socialneuron/mcp-server.

# Auth
socialneuron-mcp login [--device|--paste]
socialneuron-mcp logout
socialneuron-mcp whoami
socialneuron-mcp health

# Content (publish, quality-check, e2e workflows, plan, preset)
socialneuron-mcp sn content publish --media-url <url> --caption <text> --platforms <list> --confirm
socialneuron-mcp sn content e2e --media-url <url> --caption <text> --platforms <list> --confirm
socialneuron-mcp sn content quality-check --content "your text here"
socialneuron-mcp sn content plan list|view|approve
socialneuron-mcp sn content preset list|show|save|delete

# Analytics
socialneuron-mcp sn analytics posts --days 7 --platform youtube
socialneuron-mcp sn analytics refresh
socialneuron-mcp sn analytics loop

# System (status, credits, usage, autopilot)
socialneuron-mcp sn system status
socialneuron-mcp sn system credits
socialneuron-mcp sn system usage
socialneuron-mcp sn system autopilot

# Account (platform connections)
socialneuron-mcp sn account preflight --check-urls
socialneuron-mcp sn account oauth-health
socialneuron-mcp sn account oauth-refresh --platform instagram

# Discovery (find tools)
socialneuron-mcp sn discovery tools [--module ideation] [--scope mcp:write]
socialneuron-mcp sn discovery info

# Interactive REPL
socialneuron-mcp repl

# Add --json to any command for machine-readable output

Each grouped command also has a flat alias (e.g. sn credits ≡ sn system credits, sn publish ≡ sn content publish). The grouped form is the documented surface; flat aliases exist for shell ergonomics.

Automation Flow (E2E Loop)

The full autonomous content loop using MCP tools:

1. get_loop_summary — assess project state (content count, scheduled posts, insights)
2. plan_content_week — generate a content plan based on insights and trends
3. generate_video / generate_image — create media assets from the plan
4. check_status — poll async jobs until assets are ready
5. schedule_post — distribute content to connected platforms
6. (wait for analytics collection) — platform data is fetched automatically
7. refresh_platform_analytics — trigger a manual analytics refresh
8. get_performance_insights — read what worked and what didn't
9. Loop back to step 1 with new insights

Each iteration produces smarter content as performance data feeds back into the planning step.

Security

• All API keys are hashed before storage — we never store plaintext keys
• Credentials stored in your OS keychain (macOS Keychain, Linux secret-tool) or environment variable
• SSRF protection on all URL parameters with DNS rebinding prevention
• Rate limiting per user with per-tool limits for expensive operations
• Agent loop detection prevents runaway automation
• Telemetry is off by default — opt in with SOCIALNEURON_TELEMETRY=1

See SECURITY.md for our vulnerability disclosure policy and credential safety details.

HTTP server tuning (cloud / Railway)

The HTTP MCP server reads a few security-related env vars. Defaults are safe for the standard Railway deployment.

Telemetry

Telemetry is off by default. No data is collected unless you explicitly opt in.

To enable: Set SOCIALNEURON_TELEMETRY=1 in your environment.

To disable: DO_NOT_TRACK=1 or SOCIALNEURON_NO_TELEMETRY=1 always disables telemetry, even if SOCIALNEURON_TELEMETRY=1 is set.

When enabled, the following anonymous metrics are collected via PostHog:

• Tool name invoked
• Success or failure status
• Invocation duration (ms)

No personal content, API keys, or request payloads are ever collected. Your user ID is hashed (SHA-256) before transmission.

posthog-node is an optional dependency — if it is not installed, telemetry is a silent no-op regardless of environment variables.

Examples

See the examples/ directory:

• REST API examples — curl scripts for every endpoint
• CLI examples — automation workflows
• MCP prompts — natural language examples
• External examples repo — prompt-driven workflow templates
• Performance review and optimization loops
• Brand-aligned content generation
• Comment engagement automation

Documentation

• Tool Reference — every tool, by scope
• Authentication — device-code, browser, and API-key flows
• REST API — endpoint reference
• CLI Guide — terminal commands
• TypeScript SDK — @socialneuron/sdk
• Integration Methods — MCP vs REST vs CLI vs SDK
• Troubleshooting — common issues & fixes
• Verifying tools.lock.json — supply-chain integrity

Links

• For Developers · Pricing · Developer Settings
• OpenAPI Spec · Server Card
• Docs Site · Report an Issue · Agent Protocol

License

MIT © Social Neuron

Quick Start

MCP (AI Agents)

1. Authenticate

npx -y @socialneuron/mcp-server login --device

This opens your browser to authorize access. Requires a Social Neuron Pro plan or above (Pro = MCP read + analytics + write + distribute; Team/Agency = full MCP). See pricing.

# pnpm
pnpm dlx -y @socialneuron/mcp-server login --device

# bun
bunx -y @socialneuron/mcp-server login --device

# yarn (Classic / Berry)
yarn dlx -y @socialneuron/mcp-server login --device

# Global install (any package manager)
npm install -g @socialneuron/mcp-server   # or: pnpm add -g … / bun add -g …
socialneuron-mcp login --device

The package is published to npmjs.com with provenance attestation; any registry-compatible client works.

2. Add to Claude Code

# Local stdio (uses key from step 1)
claude mcp add socialneuron -- npx -y @socialneuron/mcp-server

# Or HTTP transport — no local process, key in header
claude mcp add --transport http socialneuron https://mcp.socialneuron.com/mcp \
  --header "Authorization: Bearer $SOCIALNEURON_API_KEY"

Add to your claude_desktop_config.json:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows: %APPDATA%\Claude\claude_desktop_config.json
• Linux: ~/.config/Claude/claude_desktop_config.json

{
  "mcpServers": {
    "socialneuron": {
      "command": "npx",
      "args": ["-y", "@socialneuron/mcp-server"]
    }
  }
}

Add to .vscode/mcp.json in your workspace:

{
  "servers": {
    "socialneuron": {
      "command": "npx",
      "args": ["-y", "@socialneuron/mcp-server"]
    }
  }
}

Add to .cursor/mcp.json in your workspace:

{
  "mcpServers": {
    "socialneuron": {
      "command": "npx",
      "args": ["-y", "@socialneuron/mcp-server"]
    }
  }
}

Add to ~/.codeium/windsurf/mcp_config.json (or via Settings → MCP servers):

{
  "mcpServers": {
    "socialneuron": {
      "command": "npx",
      "args": ["-y", "@socialneuron/mcp-server"]
    }
  }
}

Add to ~/.config/zed/settings.json under context_servers:

{
  "context_servers": {
    "socialneuron": {
      "command": {
        "path": "npx",
        "args": ["-y", "@socialneuron/mcp-server"]
      }
    }
  }
}

Add to ~/.continue/config.yaml under mcpServers:

mcpServers:
  - name: socialneuron
    command: npx
    args:
      - "-y"
      - "@socialneuron/mcp-server"

Add via Cline → MCP Servers → Edit config, or directly to ~/Library/Application Support/Code/User/globalStorage/saoudrizwan.claude-dev/settings/cline_mcp_settings.json (macOS path):

{
  "mcpServers": {
    "socialneuron": {
      "command": "npx",
      "args": ["-y", "@socialneuron/mcp-server"],
      "disabled": false,
      "autoApprove": []
    }
  }
}

3. Start using

Ask Claude: "What content should I post this week?" or "Schedule my latest video to YouTube and TikTok"

REST API (Any Language)

# Check credits
curl -H "Authorization: Bearer snk_live_..." \
  https://mcp.socialneuron.com/v1/credits

# Generate content
curl -X POST -H "Authorization: Bearer snk_live_..." \
  -H "Content-Type: application/json" \
  -d '{"topic": "AI trends", "platforms": ["linkedin"]}' \
  https://mcp.socialneuron.com/v1/content/generate

# Execute any tool via proxy
curl -X POST -H "Authorization: Bearer snk_live_..." \
  -H "Content-Type: application/json" \
  -d '{"response_format": "json"}' \
  https://mcp.socialneuron.com/v1/tools/get_brand_profile

See REST API docs | OpenAPI spec | Examples

CLI (Terminal & CI/CD)

npx @socialneuron/mcp-server sn system credits --json
npx @socialneuron/mcp-server sn analytics loop --json
npx @socialneuron/mcp-server sn discovery tools --module content

See CLI guide | Examples