SubscriberAPI MCP Server

SubscriberAPI MCP Server

An MCP (Model Context Protocol) server that lets GitHub Copilot CLI query SFMC SubscriberAPI execution logs — health checks, email lookups, execution traces, and recent errors.

Who is this for?

SFMC developers and engineers who want to troubleshoot SubscriberViaAPI issues from the terminal using natural language, for example:

• "Is the SubscriberAPI log endpoint healthy?"
• "Find recent errors for source MyForm."
• "Get the execution trace for FormRequestID abc-123."

Prerequisites

• Node.js 18 or later
• GitHub Copilot CLI
• SFMC log API endpoint URL and API key (from your team's CloudPage / API setup)

Quick start

1. Clone the repo

git clone https://github.com/YOUR-ORG/subscriberapi-mcp.git
cd subscriberapi-mcp

Tip: Clone to a folder without spaces in the path (e.g. C:\dev\subscriberapi-mcp) to avoid Windows path issues.

2. Install and build

npm run setup

3. Add your credentials

cp .env.example .env

Edit .env and set:

• SFMC_LOG_ENDPOINT — your SFMC execution log API URL
• SFMC_LOG_API_KEY — your API key

Never commit .env. It is already in .gitignore.

4. Use with GitHub Copilot CLI

This repo includes a project-level MCP config (.mcp.json) with a relative path — no machine-specific paths required.

From the cloned repo folder, start Copilot:

copilot

Copilot auto-loads .mcp.json when you work in this project. You should see subscriberapi with a green checkmark under MCP Servers.

5. Test it

Inside Copilot:

Use subscriberapi health_check and tell me the result.

Or from the shell (one-shot):

copilot -p "Call subscriberapi health_check" --allow-all-tools

MCP tools

| Tool | Description | |------|-------------| | health_check | Check if the SFMC log endpoint is available | | get_executions_by_email | Find executions by email (optional source, date range, limit) | | get_execution_trace | Get full trace for a formRequestId | | get_recent_errors | List recent errors (optional filters) |

How configuration works

| File | Purpose | |------|---------| | .mcp.json | Shared Copilot MCP config (relative dist/index.js, no secrets) | | .env | Private API credentials (each developer creates their own) | | ~/.copilot/mcp-config.json | Optional global Copilot MCP config (user-specific) |

Recommended: Rely on .mcp.json in the repo. Each developer only needs their own .env.

If you previously added subscriberapi to your global ~/.copilot/mcp-config.json with an absolute path, remove it to avoid duplicates:

copilot mcp remove subscriberapi

Optional: global install (any folder)

If you want subscriberapi available outside this repo, register it once from the cloned folder:

Windows (PowerShell):

.\scripts\register-copilot-mcp.ps1

macOS / Linux:

./scripts/register-copilot-mcp.sh

These scripts read credentials from your .env and register an absolute path on your machine only.

Development

npm run dev    # run TypeScript directly (tsx)
npm run build  # compile to dist/
npm start      # run compiled server

Troubleshooting

| Issue | Fix | |-------|-----| | Red X on subscriberapi | Run npm run build so dist/index.js exists | | Missing SFMC_LOG_ENDPOINT | Create .env from .env.example | | Path split at space (Windows) | Clone to a path without spaces, or use the register script | | Permission denied in -p mode | Add --allow-all-tools | | Duplicate subscriberapi servers | Run copilot mcp remove subscriberapi for the global entry |

License

ISC