batch-mcp — archived, superseded by batch-cep

⚠️ This repo is archived. The active project is now batch-cep — a Claude skill (Cowork / Claude Code) that wraps Batch.com via direct fetch(), without an MCP server in the middle.

Why the pivot

This repository was a TypeScript MCP server for Batch.com (CEP v2.x + MEP v1.1) — 60 typed tools, 318 Vitest specs, deployable via npm npx or HTTP on Vercel. Architecturally solid, but the target audience changed mid-project:

• Original target : developers using Claude Code / Claude Desktop with stdio MCP.
• Real target (Drivenlabs clients) : knowledge workers (CEOs, marketers, growth teams) using Claude Cowork in the browser.

Cowork accepts custom Agent Skills (uploadable .zip packages with SKILL.md + scripts) but the MCP-server route there requires OAuth 2.1 (hosted server). For a per-customer credentials model — every Batch user has their own REST API key — the OAuth route means becoming a SaaS, which contradicts the small, self-distributed spirit of the project.

The Skill+scripts approach :

• Distributes via alexandrebouchez/driven-alex-plugins marketplace (Claude Code) OR .zip upload (Cowork).
• Runs scripts locally in the Cowork sandbox — no hosting, no OAuth, no SaaS.
• Stores credentials per-customer in ${PROJECT_FOLDER}/batch-credentials.json (server-side from the user's POV, never sent anywhere except api.batch.com).
• Same 60 Batch endpoints covered — same surface, just different packaging.

Where it lives now

• Plugin : driven-alex-plugins/batch-cep
• Install Claude Code :

  claude plugin marketplace add alexandrebouchez/driven-alex-plugins
  claude plugin install batch-cep@driven-alex-plugins

• Install Cowork : zip batch-cep/skills/batch-cep/ → upload via Settings > Skills

What stays in this repo

This repo remains accessible (read-only) as a reference of Batch API surface modeling:

• 25 CEP tools fully spec'd + tested (Phase 2, merged to main, see PR #1)
• 34 MEP tools fully spec'd + tested (Phase 3, branch phase3-mep-tools, see PR #2 — closed without merge)
• Comprehensive Zod schemas, error mapping (BatchApiError), async 202 + indexing_token handling, confirm gates
• 318 Vitest specs covering RED cases, happy paths, edge cases

If you ever want to revive the MCP server angle (e.g., for users of Claude Code who prefer MCP), the code here is a complete reference implementation.

Original design docs

• Phase 2 design spec (CEP tools, 973 lines)
• Phase 3 design spec (MEP tools, 1529 lines)
• Phase 2 implementation plan
• Phase 3 implementation plan

---

Original README (archived)

What it did

Let any MCP-compatible agent (Claude Desktop, Claude Code, Cursor, Continue, the Anthropic API, ChatGPT, etc.) operate a Batch.com account: update profiles, manage audiences, send transactional pushes, orchestrate omnichannel campaigns, request data exports, and more — through a curated set of typed tools.

Every Batch endpoint that ships in their public docs was exposed as a tool. Destructive operations required an explicit confirm: true. Async 202 operations returned the indexing token so the agent could poll completion explicitly.

Install (stdio)

npx -y @alexandrebouchez/batch-mcp

Configure your client (Claude Desktop example, ~/Library/Application Support/Claude/claude_desktop_config.json):

{
  "mcpServers": {
    "batch": {
      "command": "npx",
      "args": ["-y", "@alexandrebouchez/batch-mcp"],
      "env": {
        "BATCH_REST_KEY": "your_rest_key",
        "BATCH_PROJECT_KEY": "your_project_key",
        "BATCH_IOS_LIVE_KEY": "...",
        "BATCH_ANDROID_LIVE_KEY": "..."
      }
    }
  }
}

See .env.example for the full env var list.

Install (HTTP, self-hosted on Vercel)

Once deployed, point your MCP client at https://<your-deploy>.vercel.app/api/mcp.

Development

pnpm install
pnpm dev          # starts both packages in watch mode
pnpm test
pnpm typecheck
pnpm lint

Monorepo layout:

packages/server   — @alexandrebouchez/batch-mcp (npm)
apps/web          — Next.js landing + /api/mcp endpoint (Vercel)

License

AGPL-3.0-only. If you run a modified version of this server as a service, you must publish your source under AGPL-3.0. See LICENSE.

This is intentional: it lets the community fork and improve the server freely, while preventing closed-source SaaS providers (including Batch.com itself) from absorbing the code without contributing back.

Disclaimer

This project is not affiliated with, endorsed by, or sponsored by Batch SAS. "Batch" is a trademark of its respective owner. This is an independent open-source integration built against the public Batch.com REST API.