Give your AI agent social media tools with MCP

The Model Context Protocol (MCP) lets an AI assistant call tools that run on your machine. SocialCannon ships an MCP server, so Claude, Hermes Agent or any other MCP client can draft, schedule and publish posts without you writing glue code. On Pro and above it can also read analytics, run A/B tests and answer comments. This guide sets it up, explains the tools, and covers the guardrails worth keeping.

How it works

The server is the published npm package @socialcannon/mcp@1.0.2. Your MCP client starts it locally over stdio. The server authenticates with your API client credentials, keeps a short-lived token refreshed in the background, and turns each tool call into a request to the SocialCannon REST API. Your social account tokens never reach the assistant: they stay encrypted on SocialCannon’s side.

Step 1: Create API credentials

In the SocialCannon dashboard, open Settings → API Keys. The API Credentials card shows your client ID. If you already use your credentials elsewhere, reuse that secret: pressing Generate API Secret replaces it, and anything still using the old one stops working. Otherwise, generate one now. These become SOCIALCANNON_CLIENT_ID and SOCIALCANNON_CLIENT_SECRET. The secret is shown only once; treat it like a password. Put it in your MCP host’s environment or secret settings, not in a chat message and not in a file you commit.

Step 2: Add the server to your MCP client

Most MCP hosts take a command, its arguments and the environment to start it with. Claude Desktop does not pass your shell’s variables to the server, so the credentials go in the server’s env block in claude_desktop_config.json. Replace the placeholders, and make the file readable only by you:

{
  "mcpServers": {
    "socialcannon": {
      "command": "npx",
      "args": [
        "-y",
        "@socialcannon/mcp@1.0.2"
      ],
      "env": {
        "SOCIALCANNON_CLIENT_ID": "your-client-id",
        "SOCIALCANNON_CLIENT_SECRET": "your-client-secret"
      }
    }
  }
}

Hermes Agent reads YAML. Export the two variables in the environment that starts Hermes and reference them, so the secret stays out of the file. Merge this into your existing ~/.hermes/config.yaml: if mcp_servers already exists, add socialcannon beneath it rather than creating a second key:

mcp_servers:
  socialcannon:
    command: "npx"
    args: ["-y", "@socialcannon/mcp@1.0.2"]
    env:
      SOCIALCANNON_CLIENT_ID: "${SOCIALCANNON_CLIENT_ID}"
      SOCIALCANNON_CLIENT_SECRET: "${SOCIALCANNON_CLIENT_SECRET}"

Keep the pinned version in the arguments. It means an update to the package never changes your agent’s tools without you choosing it. Never commit or sync a config file that contains the secret.

Step 3: Test with the sandbox

Restart or reload the client. Seeing the tools listed only shows the server started, so prove the credentials work with list_accounts first. An empty list is fine; it means no social account is connected yet. Then ask for exactly one create_post call with accountId: "sandbox", any text and no scheduledAt, so it runs straight away. The sandbox simulates a publication without contacting a social network, and the call succeeded only if it returns a post ID and status. If a request fails, or its outcome is unclear, stop and look at the error instead of creating more posts. Each API client gets 100 sandbox posts in total; the allowance does not reset.

The 23 tools

Each tool validates its input before calling the API. When the API refuses a request, the tool reports the HTTP status and, where there is one, a short error code such as LIMIT_EXCEEDED, but not the full error text, which stays in SocialCannon’s logs. A 400 often means a missing requirement, such as an image for Instagram; a 403 with LIMIT_EXCEEDED means a plan limit. Do not resend a request just to read its error. If a tool reports that a post may have been created, check the returned IDs with get_post or list_posts before trying again, because a second request can publish the post twice. A post that failed to publish keeps a plain-English reason, which get_post shows. The API reference describes every tool.

Guardrails worth keeping

An assistant with publishing tools can post on your behalf, so decide up front what it may do alone. A sensible default:

1. The assistant drafts posts and shows them to you.
2. You approve before anything is published or scheduled to a real account. Remember that create_post without scheduledAt publishes immediately.
3. Replies, retries, deletions and account changes also wait for your approval.

What you can ask for

• “Draft three LinkedIn posts from this changelog and schedule the one I pick for Tuesday at 9:00 UK time.”
• “Which of last week’s posts did best, and what time should I post next?”
• “Show me unread comments on yesterday’s Instagram post and suggest replies.”
• “Rewrite this announcement for X and Facebook and show me both before posting.”

Several of these need Pro or above: analytics (available for Instagram, X and YouTube; Facebook, LinkedIn and TikTok analytics are not available yet), timing suggestions, A/B tests, comment replies and posting to X. The pricing page shows what each plan includes.

Next steps

If you use OpenClaw, the OpenClaw skill guide covers the same setup through ClawHub. For direct REST integration, start with scheduling posts with one API.