Repository avatar
AI Tools
v0.2.1
active

newscatcher-mcp

com.newscatcherapi/newscatcher-mcp

Search news in any language, track coverage over time, and research companies and events.

Documentation

NewsCatcher MCP

MCP server for the NewsCatcher News API (search, exact counts, stories) and the research agent (verified event datasets, company news, company lists, monitors). Hosted on Vercel as stateless Streamable HTTP; every user brings their own NewsCatcher Platform API key.

Tool names, descriptions, defaults and output wording were tuned against model evals: change them deliberately.

Connect

Sign in with your NewsCatcher account (deployments with sign-in on): add https://<deployment>/mcp as a connector in Claude, ChatGPT or Cursor and press Connect. You sign in to the NewsCatcher platform, approve the app, and the server uses your workspace's Default API Key. No key to copy.

Or bring an API key. Get one at platform.newscatcherapi.com.

Claude Code

claude mcp add --transport http newscatcher https://<deployment>/mcp --header "x-api-key: YOUR_KEY"

Cursor / any MCP client (mcp.json)

{
  "mcpServers": {
    "newscatcher": {
      "type": "http",
      "url": "https://<deployment>/mcp",
      "headers": { "x-api-key": "YOUR_KEY" }
    }
  }
}

Authorization: Bearer YOUR_KEY works as well. Clients that cannot send headers (claude.ai custom connectors) need ?apiKey=YOUR_KEY on the URL, which is off unless the deployment sets NEWSCATCHER_ALLOW_KEY_IN_URL=1 (keys in URLs end up in access logs). Signing in avoids both.

Options on the URL

  • ?tools=news (or news,research) exposes only those toolsets, to save context. Default: all.
  • ?client=cursor tags usage in the upstream User-Agent.

Claude Code plugin (tools + 53 skills)

/plugin marketplace add Newscatcher/newscatcher-mcp
/plugin install newscatcher@newscatcher

Claude Code asks for the NewsCatcher API key once and keeps it in the OS keychain; the plugin connects to https://mcp.newscatcherapi.com/mcp with it. The skills (plugin/skills/) cover briefings, adverse media, company monitoring, sales triggers, deal, funding and layoff trackers, share of voice, PR coverage, earnings, cyber incidents and more; each one tells the model which tools to call and how to present the result. They were tuned against an end-to-end eval (37 of the 39 critical-skill test prompts at 4+ of 5 with Claude Haiku 5.5).

Tools

ToolsetToolWhat it doesCost
newssearch_newsRanked, story-grouped search over the last 30 days, any language1 / 5 / 10 credits (effort)
newslist_articlesEvery article matching a boolean query, 12 months, exact total; tally by outlet/author/country/language5 per call
newscount_articlesDaily/weekly/monthly counts for 1–5 queries, share of voice5 per bucket × query (max 60)
newsget_storyAll coverage of one story: newsrooms, earliest articles1
newsget_accountPlan, balance, limitsfree
researchstart_researchResearch agent run: events dataset or company news; dry_run estimates cost freeper run
researchget_researchWait for a run and show its table; list runsfree
researchcancel_researchStop a run (not charged)free
listssave_company_list / get_company_list / edit_company_listReusable company listsfree
monitorscreate_monitor / get_monitor / get_monitor_updates / update_monitorScheduled updates, only what is newper run / per company

Also: two guide resources (newscatcher://guides/query-syntax, newscatcher://guides/research-agent) and three prompts (news_briefing, company_watch, event_dataset).

Not in the hosted server: the local-file features of the original (export_research, save_as, csv_path). The instructions tell models so; some skills mention them for local setups.

get_research also takes exclude_rows (leave out rows after checking; counts cover the kept rows) and sort (newest, oldest, importance).

Example

A raw MCP call (after initialize), e.g. with curl:

curl -X POST https://<deployment>/mcp \
  -H "x-api-key: YOUR_KEY" -H "content-type: application/json" \
  -H "accept: application/json, text/event-stream" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"search_news","arguments":{"query":"Nvidia guidance","window":"2d","effort":"low"}}}'

Configuration

VariableDefaultPurpose
NEWSCATCHER_MAX_CALL_SECONDS240Longest one tool call works (waiting for a run, paging, counting) before answering with what it has. Keep below Vercel maxDuration (300 in vercel.json).
NEWSCATCHER_ALLOW_KEY_IN_URLoff1 accepts ?apiKey= on the MCP URL.
NEWSCATCHER_TOOLSETSallDefault toolsets when the URL has no ?tools=.
NEWSCATCHER_NEWS_API_URLapi.newscatcherapi.comNews API host only (no https://, no path).
NEWSCATCHER_NEWS_API_PORT– (443)News API port.
NEWSCATCHER_NEWS_API_ENDPOINTnews-apiNews API base path.
NEWSCATCHER_AGENT_API_URLapi.newscatcherapi.comAgent API host only.
NEWSCATCHER_AGENT_API_PORT– (443)Agent API port.
NEWSCATCHER_AGENT_API_ENDPOINTagentAgent API base path.
NEWSCATCHER_TIMEOUT_MS90000Timeout per upstream request.
NEWSCATCHER_INTEGRATION–Default User-Agent tag.
LOG_LEVELINFOJSON logs (Stackdriver shape).
POSTHOG_PROJECT_API_KEY–Enables PostHog MCP analytics (write-only phc_… key).
POSTHOG_ENABLEDtruefalse turns PostHog off completely, even with the key (e.g. on dev).
POSTHOG_APP / POSTHOG_ENVIRONMENTnewscatcher-mcp / Vercel's VERCEL_TARGET_ENV, else localSent as app and environment on every event, so one PostHog project can hold several apps and environments.
POSTHOG_HOST / POSTHOG_PORTus.i.posthog.com / 443PostHog ingestion host (region) and port.
POSTHOG_IDENTITY_SALT–Secret for pseudonymous caller ids (HMAC of the key). Without it callers stay anonymous.
NEWSCATCHER_API_KEY–Local stdio only. Never used for HTTP requests. Do not set it on Vercel.

URLs are split into host / port / endpoint; the scheme is always https and defaults point at the PROD APIs. The only secrets are the two optional PostHog values.

Sign-in with a platform account (OAuth 2.1; all of these or none, otherwise the server logs why and runs with API keys only):

VariableDefaultWhat
NEWSCATCHER_OAUTHoff1 turns sign-in on.
NEWSCATCHER_PUBLIC_URL–This deployment's own origin, e.g. https://mcp.example.com (no path; a trailing / or /mcp is dropped). Goes verbatim into the discovery documents, so set it per Vercel environment: preview and production each name themselves.
NEWSCATCHER_SUPABASE_URL–Host of the auth project users sign in to the platform with (<ref>.supabase.co). No default on purpose.
NEWSCATCHER_PLATFORM_API_URL / _PORT / _ENDPOINTplatform-api.newscatcherapi.comPlatform API that turns a signed-in user into their workspace key.

The auth project needs its OAuth 2.1 server and dynamic client registration enabled, with the authorization (consent) path pointing at the platform app. How it works: src/oauth.py.

Deploy (Vercel)

Vercel's Python runtime serves the module-level app in server.py; vercel.json gives the function 300 s. Push to the connected branch, or vercel deploy. Check https://<deployment>/health → {"ok": true, "version": …}.

Set the variables in Vercel → Project → Settings → Environment Variables, per environment:

Vercel environmentAPI it talks toWhat to set
ProductionPRODnothing for the APIs (defaults), PostHog values if wanted
Preview (branches / PRs)DEVNEWSCATCHER_NEWS_API_URL/PORT/ENDPOINT and NEWSCATCHER_AGENT_API_URL/PORT/ENDPOINT → DEV hosts

Never set NEWSCATCHER_API_KEY on Vercel: users bring their own keys.

Run locally

python -m venv .venv && .venv/Scripts/activate   # or source .venv/bin/activate
pip install -r requirements-test.txt

python server.py                                  # stdio, key from NEWSCATCHER_API_KEY
python server.py --http                           # HTTP on http://127.0.0.1:8000/mcp, key per request
docker compose up --build                         # same, in Docker, on http://localhost:8000/mcp

Test

pytest -q                                         # unit + HTTP tests, upstream mocked, no key needed
NEWSCATCHER_API_KEY=… python scripts/smoke_test.py   # live, read-only, ~6 credits

Layout

server.py                      Entrypoint: module-level `mcp` and `app` (Vercel), stdio / --http locally
src/
  server.py                    build_server / create_app, instructions, toolset + input-error middleware
  auth.py                      Key per request, 401 middleware, ?tools= / ?client=
  oauth.py                     Sign-in: discovery, client registration, platform token → workspace key
  client.py                    HTTP client: retries, pacing, no retry of paid writes, error hints
  config.py, log.py            Settings; structured JSON logging
  formatting.py, lenient.py    Compact text output; lenient list/object input
  analytics.py                 Optional PostHog
  guides.py                    Guide resources and prompts
  tools/                       news, research, lists, monitors (+ common registration, shared params)
tests/                         Tools, rendering, HTTP/auth, sign-in, analytics, skill lint

License

MIT