# MarTech MCP Server

An industry-agnostic [Model Context Protocol](https://modelcontextprotocol.io) server that exposes
marketing catalogs — offers, assets, campaigns, and computed offer metrics — to any MCP client
(Claude Desktop, other AI assistants, or an orchestration platform).

It reads catalogs from CSV today and is designed so the data source can be swapped for a database
or object storage (R2/S3) later **without changing the tools**. A customer integrates by exporting
CSVs from whatever backend they use, placing them in a configured location, and pointing the server
at it — the server and any connected AI tool never store the data and never touch the source systems.

> This is a reference implementation with a defined catalog contract, not a universal connector for
> every martech vendor. Extend the CSV contract and the `CatalogSource` to fit your systems.

## Tools

Reference lookups:
- `search_offers` — find offers by free-text query, category, and/or segment
- `get_offer` — full offer record by ID or name
- `get_assets_for_offer` — creative assets linked to an offer
- `search_campaigns` — find campaigns by query and/or segment
- `get_campaign` — full campaign record by ID or name

Computed metrics (from an event fact table; individual profiles are only ever counted, never exposed):
- `get_offer_performance` — impressions, clicks, CTR, unique reach for an offer; optional breakdown by segment or placement
- `get_top_offers` — offers ranked by CTR, optionally filtered by segment/placement
- `get_campaign_performance` — aggregate performance for a campaign

## Catalog contract (CSV)

Multi-value fields use a semicolon (`;`) delimiter.

- **offers.csv**: Offer ID, Offer Name, Offer Category, Offer Tone, Offer Segments, Offer Title, Offer Description, Offer Subtitle, Offer Eyebrow Text, Offer Image Asset URL, Offer CTA Text, Offer CTA URL, Offer CTA 2 Text, Offer CTA 2 URL
- **assets.csv**: Asset ID, Asset Name, Asset URL, Asset Tags
- **campaigns.csv**: Campaign ID, Campaign Name, Campaign Brief, Campaign Segments, Campaign Offers, Campaign Attribution IDs, Targeted Placements
- **offer_metrics.csv**: Offer ID, Placement, Segment, Profile ID, Action (View/Click), Campaign ID

## Run locally

```bash
npm install
npm run build
npm start            # runs the compiled server on stdio
# or, during development:
npm run dev          # runs from source with tsx
npm run inspect      # opens the MCP Inspector against the server
```

Set `MARTECH_DATA_DIR` to use a different catalog directory (defaults to `./data`).

## Connect to Claude Desktop

Add this to your Claude Desktop config (`claude_desktop_config.json`):

```json
{
  "mcpServers": {
    "martech": {
      "command": "node",
      "args": ["/absolute/path/to/martech-mcp-server/dist/index.js"]
    }
  }
}
```

Restart Claude Desktop, then ask things like *"What offers do we have for lapsed customers?"* or
*"What's the click-through rate for campaign TMO-CMP-001?"* — Claude will call the tools and read
your catalogs live.

## Roadmap

- Swap `CsvCatalogSource` for an R2/S3-backed source (read CSVs from a bucket) and a database source.
- Per-customer configuration (point at a customer's bucket/prefix).
- Remote transport (HTTP/SSE) for hosted, multi-client access.

## Run as a remote server (for Claude custom connectors)

The server also runs over HTTP (Streamable HTTP transport) so it can be added as a **remote
custom connector** in Claude (claude.ai, Claude Desktop, Cowork).

```bash
npm install
npm run build
npm start        # HTTP server on :3000 (or $PORT), MCP endpoint at POST /mcp
```

Health check: `GET /`  ·  MCP endpoint: `POST /mcp`

### Deploy free on Render

1. Push this repo to GitHub.
2. On render.com: New → Web Service → connect this repo.
3. Render reads `render.yaml` automatically (build `npm install && npm run build`, start `npm start`, free plan).
4. After deploy you get a URL like `https://martech-mcp-server.onrender.com`.
5. In Claude → Add custom connector → **Remote MCP server URL** = `https://martech-mcp-server.onrender.com/mcp` (leave OAuth blank).

Note: Render's free tier sleeps after inactivity; the first request after idle may take ~30–60s to wake.

### Run locally for Claude Desktop (stdio)

```bash
npm run build
npm run start:stdio
```
Then point `claude_desktop_config.json` at `dist/index.js` (see earlier example).