Repository avatar
AI Tools
v0.1.0
active

mcp

io.github.campaign-swarm/mcp

Run social campaigns end to end: plan, create, schedule, publish, measure, and optimize.

Documentation

Campaign Swarm MCP

Campaign Swarm is an AI campaign workspace for agencies. This server exposes the campaign workflow over the Model Context Protocol: plan a campaign, create and adapt content, schedule posts, inspect performance, and review the approval queue from Claude, Cursor, VS Code, or any MCP-compatible client.

Hosted endpoint

https://mcp.campaignswarm.com/mcp

Transport: streamable HTTP.

The hosted server uses the same organization API keys as the Campaign Swarm dashboard. Create a key in Settings → API keys, then send it as a bearer token:

Authorization: Bearer csw_...

Anonymous requests receive 401. The key resolves the organization and role on the API; read tools work for any valid key, and write tools require an editor, admin, or owner key.

OAuth 2.1 for Claude and OpenAI

The hosted endpoint also supports OAuth 2.1 authorization-code + PKCE for clients that require OAuth. Discovery is published at:

https://mcp.campaignswarm.com/.well-known/oauth-protected-resource/mcp
https://mcp.campaignswarm.com/.well-known/oauth-authorization-server

The server supports Client ID Metadata Documents (CIMD), Dynamic Client Registration (DCR), S256 PKCE, resource indicators, refresh-token rotation, and the mcp:tools scope. The consent page asks for a Campaign Swarm API key; use a read-only key for evaluation. The key is sent only to Campaign Swarm, is encrypted in the authorization store, and is never placed in a URL.

OAuth is enabled on the server by setting OAUTH_ENCRYPTION_KEY and a writable OAUTH_STATE_FILE; see .env.example. API-key clients continue to work with or without OAuth enabled.

The hosted service is running this build with OAuth enabled as of 2026-11-15. Both discovery endpoints return 200, and a full authorization, refresh, and restart-persistence flow has passed against https://mcp.campaignswarm.com. API-key clients continue to work unchanged. The service stores clients and tokens in a mode-600 state file on persistent disk; it is single-process state, so do not run multiple MCP replicas against the same file.

Client configuration

Claude Desktop / Claude Code

OAuth (preferred; live in production) — no header is needed:

{
  "mcpServers": {
    "campaign-swarm": {
      "type": "http",
      "url": "https://mcp.campaignswarm.com/mcp"
    }
  }
}

API-key fallback:

{
  "mcpServers": {
    "campaign-swarm": {
      "type": "http",
      "url": "https://mcp.campaignswarm.com/mcp",
      "headers": {
        "Authorization": "Bearer csw_REPLACE_WITH_YOUR_KEY"
      }
    }
  }
}

Cursor

Add a remote MCP server named campaign-swarm with the URL above and the same Authorization header.

VS Code

{
  "servers": {
    "campaign-swarm": {
      "type": "http",
      "url": "https://mcp.campaignswarm.com/mcp",
      "headers": {
        "Authorization": "Bearer csw_REPLACE_WITH_YOUR_KEY"
      }
    }
  }
}

Tool surface

The server exposes 35 tools: 20 read tools and 15 write tools. Read tools cover connected accounts, pages, posts, comments, plans, projects, schedules, publish queue, ads, content assets, planner stages, and performance. Write tools cover projects, content items, post drafts, schedules, planner runs, ads budgets/pauses, comment replies, and performance learnings.

Write tools never publish or approve silently. They create drafts, schedules, or approval items for a human to review in Campaign Swarm. The server does not expose raw SQL, arbitrary HTTP requests, publish, approval, or human-gate bypasses.

Local development

pnpm install
pnpm typecheck
pnpm test
MCP_PORT=3101 INTERNAL_API_URL=http://localhost:8000 ./run-mcp.sh

The process binds to loopback by default. TLS is terminated by the reverse proxy in production.

Links

No installation packages available.