sprout-mcp

Read-only MCP server over the Sprout Social public API. 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

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

.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.

.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.