mcp-brandwatch

MCP server for the Brandwatch Consumer Research API, Data Upload API and Analysis API.

📋 Reviewing this? Start with IT-REVIEW.md — architecture, auth model, risk assessment, tool inventory and the open decisions. This README is the operator quick-reference.

Two flavours:

• worker/ — remote server on Cloudflare Workers (connector URL). Primary.
• server.py — local stdio server (subset). Legacy/local use.

Remote server (Cloudflare Worker)

Deployed at: https://mcp-brandwatch.gtm-ai.workers.dev

Connector URL (secret path — treat as a credential, it is in worker/.mcp-secret):

https://mcp-brandwatch.gtm-ai.workers.dev/<MCP_SECRET>/mcp

/sse also available for legacy SSE clients. Requests without the secret prefix get 404.

Secrets

cd worker
npx wrangler secret put BW_TOKEN        # long-lived API token — preferred
# or:
npx wrangler secret put BW_USERNAME
npx wrangler secret put BW_PASSWORD
npx wrangler secret put MCP_SECRET      # URL path key (already set)

Only "Regular" or "Admin" Brandwatch accounts can use the API. Tokens come from POST https://api.brandwatch.com/oauth/token (grant_type=api-password, client_id=brandwatch-api-client) and last ~1 year.

Deploy / dev

cd worker
npm install --legacy-peer-deps
npm run deploy      # or: npm run dev

Tools (55)

Group	Tools
Account	me, get_user, get_client
Projects	list_projects, get_project
Queries	list_queries, get_query, validate_query, create_query, update_query, delete_query
Query groups	list_query_groups, delete_query_group
Tags	list_tags, create_tag, delete_tag, backfill_tag
Categories	list_categories, create_category, delete_category, backfill_category
Rules	list_rules, get_rule, delete_rule
Author/site/location lists	list_groups, create_group, delete_group
Workflow & alerts	get_workflow, list_alerts, get_alert, create_alert, update_alert, delete_alert
Mentions	get_mentions (paged + cursor, fulltext), count_mentions, update_mentions
Charts & insights	chart, multi_aggregate_chart, topics, data_insights (hashtags/emoticons/urls/mentionedauthors/sharedsites)
Metadata	list_filters, list_metrics, search_locations, list_exclusion_snippets
Data Upload	list_content_sources, create_content_source, update_content_source, delete_content_source, upload_documents, delete_documents, content_upload_usage
Analysis (billed per query)	analysis_submit, analysis_result, analysis_usage
Escape hatch	brandwatch_request (any method, any path)

Rate limit & optimisations baked in

• Consumer Research API: 30 calls / 10 min per client (x-rate-limit headers). The worker appends _rateLimit to responses once usage hits 70% so the model backs off.
• Metadata endpoints (tags, categories, lists, filters, metrics, locations, exclusion snippets) cached in-memory 5 min — Brandwatch's own recommended practice.
• multi_aggregate_chart and count_mentions exist specifically to spend fewer calls.
• OAuth token cached per isolate; auto-refresh once on 401.
• Dates: ISO 8601 (2024-01-01 or 2024-01-01T00:00:00.000+0000). Analysis API ranges max 24h. Mentions pagination caps at 10,000 — use cursor beyond.

Refs: https://developers.brandwatch.com/llms.txt, Python client BrandwatchLtd/bcr-api.