Publer Gateway MCP

One safe MCP doorway into every Publer workspace you manage.

Publer Gateway MCP is a TypeScript MCP server for teams, agencies, and solo builders who use Publer across more than one brand, business, client, or social account set. It gives Codex, Claude, and other MCP clients a careful way to discover Publer workspaces, map projects to the right account defaults, preview scheduling payloads, and only perform live writes after explicit approval.

It is built for the work that happens before the post goes out: choosing the right workspace, checking the right accounts, preparing platform-aware payloads, reviewing the dry run, and keeping secrets out of the repo.

Why This Exists

Most social scheduling automations assume one account, one workspace, one happy path. Real Publer usage is messier:

• one API key may see multiple businesses or workspaces

• one repo may map to a specific client, brand, or product

• posts need preview and approval before a scheduling write

• agents need guardrails so they do not publish to the wrong account

• API keys must stay local, server-side, and out of chat transcripts

Publer Gateway MCP turns that into a safer workflow.

flowchart LR
  A["Codex / Claude / MCP client"] --> B["Publer Gateway MCP"]
  B --> C["Local secret env<br/>PUBLER_API_KEY"]
  B --> D["Local non-secret defaults<br/>project -> workspace/accounts"]
  B --> E["Publer API"]
  E --> F["Workspaces"]
  E --> G["Accounts"]
  E --> H["Posts, media, jobs, analytics"]

Related MCP server: @fopost/mcp

What You Get

• Workspace-aware Publer access from a single MCP server.

• Project defaults stored locally outside app repos by default.

• Read tools for workspaces, accounts, posts, jobs, best times, and analytics.

• Write-capable tools that preview first and require dryRun: false plus confirm: true.

• Reusable Codex/agent skills for safe Publer workflows.

• Mocked tests, MIT license, security notes, examples, and CI.

Safety Model

Publer Gateway MCP is intentionally conservative.

Tool Surface

Install

npm install
npm run build
npm test

Run the MCP server with your MCP client. Set PUBLER_API_KEY through the client environment, a local process manager, or a trusted secret manager. Avoid putting real keys directly in shell commands that may be saved to history.

Configuration

MCP Client Examples

Codex

{
  "mcpServers": {
    "publer-gateway": {
      "command": "node",
      "args": ["/absolute/path/to/publer-gateway-mcp/dist/src/index.js"],
      "env": {
        "PUBLER_API_KEY": "set-this-locally",
        "PUBLER_DEFAULT_DRY_RUN": "true"
      }
    }
  }
}

Claude Desktop

{
  "mcpServers": {
    "publer-gateway": {
      "command": "node",
      "args": ["/absolute/path/to/publer-gateway-mcp/dist/src/index.js"],
      "env": {
        "PUBLER_API_KEY": "set-this-locally",
        "PUBLER_DEFAULT_DRY_RUN": "true"
      }
    }
  }
}

Recommended Workflow

1. Call publer_list_workspaces.

2. Pick the correct business/workspace.

3. Call publer_list_accounts for that workspace.

4. Call publer_set_project_default with the project path, workspace ID, and target account IDs.

5. Call publer_preview_schedule_post.

6. Review workspace, accounts, schedule, copy, media, and platform payload.

7. Only after explicit approval, call publer_schedule_post with dryRun: false and confirm: true.

8. Poll publer_get_job_status if Publer returns a job ID.

Included Agent Skills

The skills/ folder is part of the product, not an afterthought. These skills teach future agents how to use the MCP without drifting into unsafe publishing behavior.

Copy these folders into a compatible Codex skill directory or package them with your own agent setup.

Example Preview Call

{
  "projectPath": "/work/acme-launch",
  "text": "Launch week starts now. See what shipped today.",
  "scheduledAt": "2026-07-14T15:00:00Z"
}

The preview tool returns the exact Publer payload it would send. The live scheduling tool will not call Publer unless the caller adds:

{
  "dryRun": false,
  "confirm": true
}

Development

npm install
npm run build
npm test
npm pack --dry-run

Tests use mocked Publer responses and do not call real Publer endpoints.

Project Plan

See docs/PROJECT_PLAN.md for the v1 milestone breakdown and acceptance criteria.

Security

See SECURITY.md. The short version: do not paste Publer secrets into chat, do not commit .env, and do not grant live write approval until the exact payload is reviewed.

License

MIT. Use it, fork it, improve it, and ship safer social automation.