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

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.

Area	Default behavior
API keys	Read from local environment only. Never stored in project defaults.
Project defaults	Store workspace/account IDs only. No secrets.
Read tools	May call Publer directly.
Write tools	Return previews unless the call explicitly sets dryRun: false and confirm: true.
Media URL previews	Redact full URL; show host only to avoid leaking signed URLs.
Errors	Return safe status/message without API keys or raw auth headers.

Tool Surface

Tool	Purpose	Write risk
publer_list_workspaces	List available Publer businesses/workspaces.	Read
publer_list_accounts	List connected social accounts in a workspace.	Read
publer_get_project_default	Read local project routing defaults.	Local read
publer_set_project_default	Set local workspace/account defaults for a project.	Local write
publer_preview_schedule_post	Build a Publer schedule payload without calling Publer writes.	Preview
publer_schedule_post	Schedule a post only with explicit live-write confirmation.	Publer write
publer_list_posts	List scheduled, draft, failed, or published posts.	Read
publer_upload_media_from_url	Import media from a URL, preview-first.	Publer write
publer_get_job_status	Poll async Publer jobs.	Read
publer_get_best_times	Retrieve best-time suggestions for an account.	Read
publer_get_analytics	Retrieve analytics charts or post insights.	Read

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

Name	Required	Default	Description
PUBLER_API_KEY	yes	none	Publer API key from your local Publer account settings.
PUBLER_BASE_URL	no	https://app.publer.com/api/v1	Override for testing or future API changes.
PUBLER_DEFAULT_DRY_RUN	no	true	Keeps write-capable tools in preview mode by default. Live writes still require call-level dryRun: false.
PUBLER_DEFAULTS_PATH	no	OS config folder	Path for non-secret project default mappings.

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.

Skill	Use it for
publer-gateway	General safe use of the MCP server.
publer-social-scheduler	Preparing, previewing, and scheduling approved social content.
publer-workspace-router	Mapping projects, repos, clients, and brands to Publer workspace/account defaults.
publer-analytics-reviewer	Retrieving and interpreting Publer analytics and best-time suggestions.

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.