@socialneuron/mcp-server

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

This npm package registers 75 tools over stdio. The hosted endpoint mcp.socialneuron.com and REST API expose the full 92-tool product surface — 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.

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; 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

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"

{
  "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"]
    }
  }
}

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

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

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

{
  "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

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

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