# googlenews-mcp

MCP server in front of Google News, so agents **without external internet
access** can still read the news: the agent talks only to this server, and
this server talks only to `news.google.com`. It is a news gateway, not a web
proxy — there is deliberately no fetch-arbitrary-URL tool.

- **Image:** `ghcr.io/robertdwhite/googlenews-mcp`, built by CI in this repo.
- **Transport:** MCP streamable HTTP at `/mcp`, bearer-gated by `MCP_TOKEN`.
  `/healthz` is open.
- **Upstream:** Google News public RSS endpoints (no API key), plus the
  `batchexecute` RPC used only to decode article redirect URLs.

## Tools

| Tool | Does |
| --- | --- |
| `top_headlines(language, country, count)` | Front-page top stories |
| `topic_headlines(topic, ...)` | One section: WORLD, NATION, BUSINESS, TECHNOLOGY, ENTERTAINMENT, SCIENCE, SPORTS, HEALTH |
| `search_news(query, when, ...)` | Full-text search; supports Google News operators (`site:`, `source:`, `after:`/`before:`, `"..."`, `OR`, `-`) and a `when` recency window (`1h`…`1m`) |
| `geo_headlines(location, ...)` | Local news for a city/region/country |
| `decode_urls(urls)` | Resolve `news.google.com/rss/articles/...` redirect links to real publisher URLs (best-effort, max 10/call) |

Articles come back as `{title, url, published, source, source_url, summary,
related}`; `related` carries other outlets' coverage when Google clusters a
story.

## Config (env)

| Var | Meaning |
| --- | --- |
| `MCP_TOKEN` | Bearer token required on `/mcp`. Unset = unauthenticated (dev only). |
| `PORT` | Listen port (default 8080). |
| `GNEWS_LANGUAGE` / `GNEWS_COUNTRY` | Default locale (`en` / `US`). |
| `GNEWS_TIMEOUT` | Upstream timeout seconds (default 30). |

## Run locally

```sh
pip install -r requirements.txt
python server.py
curl localhost:8080/healthz
```

## Deploy

Manifests live in
[whitehouse-rke2](https://github.com/RobertDWhite/whitehouse-rke2) under
`apps/ai/googlenews-mcp` (namespace `googlenews-mcp`, endpoint
`https://googlenews-mcp.internal.white.fm/mcp`, tailnet only).

## Notes

- `decode_urls` uses the same technique as the `googlenewsdecoder` package;
  Google changes that endpoint occasionally, so treat it as best-effort. The
  redirect URLs themselves also work directly in a normal browser.
- Google clusters top-stories items; the per-item `related` list is parsed out
  of the RSS description HTML.