@socialneuron/mcp-server

91 public MCP tools for AI-powered social media management. Create content, schedule posts, track analytics, and optimize performance — all from Claude Code or any MCP client.

Quick Start

1. Connect the hosted MCP

The hosted endpoint needs no local npm process:

https://mcp.socialneuron.com/mcp

• Claude Web: open claude.ai/customize/connectors, choose Add custom connector, enter the URL above, then approve OAuth.
• Claude Code: claude mcp add --transport http socialneuron https://mcp.socialneuron.com/mcp
• Codex Desktop/CLI: codex mcp add socialneuron --url https://mcp.socialneuron.com/mcp, then codex mcp login socialneuron if prompted. Codex Desktop reads the same MCP configuration.

2. Or run locally over stdio

Authenticate first:

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

This opens your browser to authorize access. Requires a Social Neuron Pro plan or higher. See pricing.

Then add the local process 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"

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 post to X and Bluesky 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

The hosted endpoint and npm stdio server each expose 91 public tools. Their surfaces differ intentionally: hosted HTTP includes the Content Calendar and Analytics Pulse MCP Apps, while stdio includes 2 local screen-capture tools instead. The live hosted count is published by the server card. A small set of internal service tools used by Social Neuron's own automation are registered but not part of the public surface.

MCP App support is host-dependent. Every App tool returns a normal structured/text fallback, so scheduling and analytics still work when a host does not render the interactive widget.

These tools are available to AI agents (Claude, Cursor, etc.) via the MCP protocol.

Content Lifecycle

Management & Optimization

Utilities

Interactive MCP Apps (hosted HTTP)

Apps render only in MCP hosts that support the MCP Apps extension. All underlying data and write operations remain ordinary scoped tools, so hosts without interactive UI can use the same workflows through text/tool calls.

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 a file fallback created with owner-only permissions where the operating system supports them.

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/API 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

# 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 available 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
• Set DO_NOT_TRACK=1 to disable anonymous usage telemetry

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

Telemetry

This package collects operational usage metrics (tool name, duration, success/failure) to improve reliability. It does not send tool inputs, outputs, generated content, API keys, emails, or upstream error bodies. When a deployment configures POSTHOG_PSEUDONYMIZATION_KEY, the user identifier is HMAC-pseudonymized; otherwise an ephemeral per-process key prevents stable cross-session correlation.

To disable: Set DO_NOT_TRACK=1 or SOCIALNEURON_NO_TELEMETRY=1 in your environment.

No personal content, API keys, or request payloads are ever collected.

Examples

See the examples repo for prompt-driven workflow templates:

• Weekly content batch planning
• Cross-platform content repurposing
• Performance review and optimization loops
• Brand-aligned content generation
• Comment engagement automation

Links

• Social Neuron
• For Developers
• Documentation
• Examples
• Agent Protocol
• Developer Settings
• Pricing

License

MIT - see LICENSE