# sprout-mcp

Read-only MCP server over the [Sprout Social public API](https://api.sproutsocial.com/docs/).
Exposes profile and post analytics as tools, returning the API's own JSON
unmodified so downstream inject skills do the shaping.

No write tools. Nothing here can create, schedule, edit, or delete a post.

## Tools

| Tool | Method | Endpoint |
| --- | --- | --- |
| `get_customer_id` | GET | `/v1/metadata/client` |
| `list_profiles` | GET | `/v1/{customer_id}/metadata/customer` |
| `get_profile_metrics` | POST | `/v1/{customer_id}/analytics/profiles` |
| `get_post_performance` | POST | `/v1/{customer_id}/analytics/posts` |
| `list_metrics` | — | local catalog, no API call |

`list_profiles` is the entry point: every analytics call is scoped by
`customer_profile_id`, and that is the only place those IDs come from.

`list_metrics` was added beyond the original build list because Sprout's metric
keys are network-specific and not guessable (`impressions` on Instagram is
labelled "Views"; TikTok profile counters are `*_total`; a handful require
Premium Analytics). It serves a catalog generated from the published docs so
calls don't fail on invented key names. Drop it if you'd rather keep the
surface at four tools.

## Setup

```bash
python -m venv .venv && .venv/Scripts/python.exe -m pip install -e .
```

Set two environment variables (see `.env.example`):

- `SPROUT_API_TOKEN` — generate in Sprout under **Settings > Global Features > API**
- `SPROUT_CUSTOMER_ID` — optional; if unset the server calls `/v1/metadata/client`
  and infers it, which only works when the token sees exactly one customer

### Claude Desktop

Copy `claude_desktop_config.example.json` into
`%APPDATA%\Claude\claude_desktop_config.json`, fill in the token, and restart
Claude Desktop. The `command` path already points at this checkout's venv.

## Behavior worth knowing

**Raw passthrough.** Responses are returned exactly as Sprout sent them. The one
structural change is pagination: with `all_pages=true` (default) the `data`
arrays from each page are concatenated and `paging` is annotated with
`pages_fetched`, `pages_available`, and `truncated`. Individual records are
never touched. Set `all_pages=false` for a single page.

**Rates are not returned by the API.** Sprout's engagement rate, engagements,
and similar figures are *calculated* metrics — the API returns only the raw
counts they're derived from. `list_metrics` includes the formulas Sprout uses
under `calculated_profile_metrics` / `calculated_post_metrics`. Compute them
downstream; don't expect them in a response.

**Rate limits.** Sprout allows 60 requests/minute and 250,000/month. The client
holds itself under 60/min with a sliding window, so long paginated pulls
throttle rather than 429. On a 429 or 5xx it retries up to 5 times with
exponential backoff, honoring `Retry-After`. 4xx responses are not retried —
they're returned as `ERROR: ...` including the status code and Sprout's own
response body, so a bad metric key tells you which key.

**Documented request caps**, enforced client-side before a call is spent:
max 100 profiles per request; max 1-year `reporting_period` for profile
analytics. Profile analytics pages at 1000 records, post analytics at 50.

**Date formats** differ by endpoint and are validated:
`get_profile_metrics` takes `YYYY-MM-DD` (end exclusive);
`get_post_performance` takes `YYYY-MM-DDTHH:MM:SS` (both inclusive).

## Tests

```bash
.venv/Scripts/python.exe test_server.py
```

41 offline checks — tool registration, request-body and filter-syntax
construction, input validation, pagination merging and capping, 429 retry, 4xx
error surfacing, customer-ID discovery, and metric-catalog integrity. httpx is
stubbed with `MockTransport`, so no live API calls and no token needed.

```bash
.venv/Scripts/python.exe stdio_check.py
```

Launches the server as a real MCP stdio subprocess and lists its tools.

## Regenerating the metric catalog

`sprout_mcp/metrics.json` was scraped from the docs on the date in its
`_retrieved` field. Sprout deprecates metrics periodically (Meta dropped several
Facebook impression metrics in 2025–2026), so re-scrape if keys start failing.
The catalog is reference data only — it never gates a request, so an out-of-date
entry can't block a valid call.