Buildo AI — MCP Server

A production-ready Model Context Protocol server that exposes Buildo AI's marketing capabilities to Claude Desktop, Cursor, Make, Zapier, and any other MCP-compatible client.

Tools

| Tool | Description | Required Permission | |------|-------------|---------------------| | buildo_get_business_profile | Returns business name, industry, offer, channels, plan | campaigns:read | | buildo_generate_campaign | Generates full campaign: 3 ad copies + 2 creative briefs | campaigns:write | | buildo_analyze_campaign_performance | Analyzes Meta Ads metrics, returns scale/optimize/pause decision | reports:read | | buildo_get_leads | Fetches CRM leads with status filter | leads:read | | buildo_generate_whatsapp_followup | Generates personalized Hebrew WhatsApp message for a lead | whatsapp:write + leads:read | | buildo_get_clarity_insights | Analyzes Microsoft Clarity behavior data for a website | clarity:read | | buildo_create_weekly_marketing_report | Generates weekly marketing summary report | reports:read | | buildo_generate_landing_page_feedback | Conversion-focused landing page audit | campaigns:read |

Transports

stdio (Claude Desktop / Cursor)

The process runs as a subprocess of the MCP client. Auth uses BUILDO_API_KEY env var.

HTTP (Make / Zapier / custom integrations)

POST/GET /mcp with Authorization: Bearer <api-key>. One server handles all businesses — each request is authenticated per-request.

Setup

1. Install dependencies

cd mcp-server
npm install

2. Configure environment

cp .env.example .env
# Edit .env with your values

3. Run in development (stdio)

BUILDO_API_KEY=demo_key_abc123 npm run dev

4. Run in HTTP mode

MCP_TRANSPORT=http PORT=3100 npm run dev

5. Build for production

npm run build
npm start

Claude Desktop Configuration

Add to ~/Library/Application Support/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "buildo": {
      "command": "node",
      "args": ["/path/to/mcp-server/dist/index.js"],
      "env": {
        "BUILDO_API_KEY": "your_api_key_here"
      }
    }
  }
}

API Keys

Built-in test keys

| Key | Business | |-----|----------| | demo_key_abc123 | Demo Fitness Studio | | acme_key_xyz789 | Acme Real Estate |

Adding custom keys via env vars

BUILDO_KEY_MY_BUSINESS=my_secret_key_here

This creates a default business context with starter plan permissions.

Architecture

src/
├── index.ts          # Entry point — selects transport
├── server.ts         # MCP server creation + transport wiring
├── context.ts        # BusinessContext resolution per transport
├── auth.ts           # API key validation + MOCK_BUSINESSES registry
├── types.ts          # All TypeScript interfaces
├── services/
│   ├── buildoApi.ts  # CRM / lead data
│   ├── metaAds.ts    # Meta Ads API integration
│   ├── clarityService.ts  # Microsoft Clarity integration
│   └── crm.ts        # WhatsApp message generation
└── tools/
    ├── campaigns.ts  # buildo_get_business_profile + buildo_generate_campaign
    ├── leads.ts      # buildo_get_leads
    ├── performance.ts # buildo_analyze_campaign_performance
    ├── clarity.ts    # buildo_get_clarity_insights
    ├── whatsapp.ts   # buildo_generate_whatsapp_followup
    ├── reports.ts    # buildo_create_weekly_marketing_report
    └── landingPage.ts # buildo_generate_landing_page_feedback

Environment Variables

| Variable | Default | Description | |----------|---------|-------------| | MCP_TRANSPORT | stdio | stdio or http | | PORT | 3100 | HTTP port | | BUILDO_API_KEY | — | API key for stdio mode | | BUILDO_BACKEND_URL | — | Buildo backend URL (production) | | META_ADS_ACCESS_TOKEN | — | Meta Marketing API token | | META_AD_ACCOUNT_ID | — | Meta ad account ID | | CLARITY_API_TOKEN | — | Microsoft Clarity API token | | CLARITY_PROJECT_ID | — | Clarity project ID | | LOG_LEVEL | info | debug, info, warn, error |

Production Notes

• Replace MOCK_BUSINESSES in auth.ts with a real GET /api/v1/mcp/auth call to the Buildo backend.
• Replace mock data in services/ with real API integrations.
• All logs go to stderr — never to stdout (which is reserved for the MCP protocol).
• Sensitive keys are automatically redacted from logs.