@socialneuron/mcp-server

73 tools for AI-powered social media management. MCP, REST API, CLI — create content, schedule posts, track analytics, and optimize performance.

Integration Methods

All methods share the same 73 tools, auth, scopes, and credit system. Compare methods.

Quick Start

MCP (AI Agents)

1. Authenticate

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

This opens your browser to authorize access. Requires a paid Social Neuron plan (Starter or above). See pricing.

2. Add to Claude Code

claude mcp add socialneuron -- npx -y @socialneuron/mcp-server

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

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

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

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

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 image to Instagram and LinkedIn 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 (73 tools)

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

All tools are accessible via MCP, REST API (POST /v1/tools/{name}), and CLI.

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 paid plan:

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

# Deterministic CLI (no LLM)
socialneuron-mcp sn publish --media-url <url> --caption <text> --platforms <list> --confirm
socialneuron-mcp sn status --job-id <id>
socialneuron-mcp sn posts --days 7 --platform youtube
socialneuron-mcp sn refresh-analytics
socialneuron-mcp sn preflight --check-urls
socialneuron-mcp sn oauth-health --json
socialneuron-mcp sn oauth-refresh --platform instagram
socialneuron-mcp sn quality-check --content "your text here"
socialneuron-mcp sn autopilot
socialneuron-mcp sn usage
socialneuron-mcp sn loop
socialneuron-mcp sn credits

# Agent-native CLI v2
socialneuron-mcp sn tools [--module ideation] [--scope mcp:write]  # List/filter all 73 tools
socialneuron-mcp sn info                                            # Version, auth, credits, tool count
socialneuron-mcp sn plan list|view|approve                          # Content plan management
socialneuron-mcp sn preset list|show|save|delete                    # Platform presets (6 built-in)

# Interactive REPL
socialneuron-mcp repl

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

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.

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

Links

• For Developers — Integration methods, tools, pricing
• REST API Docs — Endpoint reference
• CLI Guide — Terminal commands
• Integration Methods — Compare MCP vs REST vs CLI
• OpenAPI Spec — Machine-readable API spec
• Developer Settings — Generate API keys
• Documentation
• Pricing
• Agent Protocol

License

MIT - see LICENSE