Social Champ MCP server

Social Champ MCP server

A Model Context Protocol (MCP) server for the Social Champ platform. It exposes the full Social Champ tool catalog to MCP-compatible AI clients such as Claude Desktop, Claude Code, and Cursor: scheduling and managing posts, managing connected channels and workspaces, labels, queues, recycling, shareable calendars, agency approval workflows, and the AI content wizard.

Tools

This server mirrors the live Social Champ MCP tool catalog. Channels are connected social profiles; workspaces group channels and shareable calendars. The tool definitions are generated from tools.schema.json, a snapshot of the live server's catalog, so the full set of tools, argument names, and descriptions stays in parity with the hosted server.

Tools are grouped by domain:

• Posts: create, update, delete, bulk schedule, browse, reorder the queue, set Instagram first comment.
• Channels: list, filter, fetch one, location search.
• Workspaces: list.
• Calendars: view options, in-app URL, shareable calendar create, list, update, delete.
• Queue: pause, resume, clear.
• Labels: list, create, apply, remove, bulk apply.
• Recycling: list collections, recycle a post.
• Agency workflows: list pending approvals, approve, reject, remind approvers, bulk delete.
• AI wizard: generate a post, suggest hashtags, rewrite, generate images.

Each tool is annotated with ToolAnnotations so clients can apply the right confirmation behavior. Read-only tools carry readOnlyHint=True; destructive tools (deletepost, deleteshareablecalendar, bulkdelete, queueclear) carry destructiveHint=True. Agency tools require the caller token to also carry the manageteam scope; this is noted in each tool's description.

For the full per-tool list with required arguments and scopes, see tools.schema.json here, or api/mcp/IMPLEMENTED.md in the auth repo.

Requirements

OAuth2 scopes used by the published tools are readprofile and managepost.

• Python 3.10 or newer.
• A Social Champ API key or OAuth2 access token. Both are sent as a Bearer token.

Install

With uv:

uv pip install socialchamp-mcp

With pip:

pip install socialchamp-mcp

From source:

git clone https://github.com/socialchamp/socialchamp-mcp.git
cd socialchamp-mcp
pip install -e ".[dev]"

Configuration

Set configuration through environment variables.

Copy .env.example to .env for local use. Never commit .env.

MCP client setup

Claude Desktop

Add the server to claudedesktopconfig.json:

{
  "mcpServers": {
    "socialchamp": {
      "command": "socialchamp-mcp",
      "env": {
        "SOCIALCHAMP_API_KEY": "your-api-key"
      }
    }
  }
}

If the console script is not on your PATH, use "command": "python" with "args": ["-m", "socialchamp_mcp"].

Claude Code

claude mcp add socialchamp --env SOCIALCHAMP_API_KEY=your-api-key -- socialchamp-mcp

Running over HTTP

The default transport is stdio, which is what Claude Desktop and Claude Code use. To run over HTTP instead, set SOCIALCHAMP_TRANSPORT:

SOCIALCHAMP_TRANSPORT=streamable-http SOCIALCHAMP_API_KEY=your-api-key socialchamp-mcp

sse is also supported. Point your client at the resulting HTTP endpoint.

Mapping to the real API

Shortened. The full README is on GitHub.