# @gridnews/mcp

MCP server for [GridNews](https://gridnews.io) — market news, press releases, and sentiment for AI agents.

Gives any MCP-capable assistant the latest market coverage: story clusters ranked
by how many independent outlets corroborated them, article search across thousands
of sources, per-ticker news with an aggregate sentiment reading, primary-source
wire releases, and trending topic clusters. With a Pro key it can also run Grid AI
research: read documents or search results and return verbatim, cited excerpts, with
an optional comparison across them.

## Install

Requires Node.js 20+ and a GridNews API key. `get_topics` works without a key;
every other tool needs one.

### Claude Code

```bash
claude mcp add gridnews --env GRIDNEWS_API_KEY=your_key -- npx -y @gridnews/mcp
```

### Claude Desktop

Add to `claude_desktop_config.json`:

```json
{
  "mcpServers": {
    "gridnews": {
      "command": "npx",
      "args": ["-y", "@gridnews/mcp"],
      "env": { "GRIDNEWS_API_KEY": "your_key" }
    }
  }
}
```

### Cursor

Add to `.cursor/mcp.json`:

```json
{
  "mcpServers": {
    "gridnews": {
      "command": "npx",
      "args": ["-y", "@gridnews/mcp"],
      "env": { "GRIDNEWS_API_KEY": "your_key" }
    }
  }
}
```

### OpenAI Codex

```bash
codex mcp add gridnews --env GRIDNEWS_API_KEY=your_key -- npx -y @gridnews/mcp
```

### Gemini CLI

Add to `~/.gemini/settings.json`:

```json
{
  "mcpServers": {
    "gridnews": {
      "command": "npx",
      "args": ["-y", "@gridnews/mcp"],
      "env": { "GRIDNEWS_API_KEY": "your_key" }
    }
  }
}
```

## Configuration

| Variable | Default | Purpose |
|----------|---------|---------|
| `GRIDNEWS_API_KEY` | — | Your API key. Required for everything except `get_topics`. |
| `GRIDNEWS_BASE_URL` | `https://api.gridnews.io` | Override the API host. |
| `GRIDNEWS_TIMEOUT_MS` | `30000` | Per-request timeout. Raise it if you use `get_symbol_sentiment` heavily. |
| `GRIDNEWS_WS_URL` | `wss://stream.gridnews.io` | Override the stream host `research` and `get_research` connect to. |

## Tools

| Tool | Purpose | Minimum tier |
|------|---------|--------------|
| `get_top_events` | The biggest stories now, as clusters ranked by independent corroboration | free (filters need basic) |
| `get_event_detail` | Every outlet that carried one story, grouped by independent voice | free |
| `search_news` | Search articles and press releases by text, symbol, source, date, sentiment, and quality | free (filters need basic) |
| `get_symbol_news` | Recent coverage for one ticker, plus an aggregate sentiment reading | free |
| `get_symbol_sentiment` | Sentiment analysis for a ticker over a timeframe, with its basis | pro |
| `list_press_releases` | Wire releases filtered by symbol, provider, company, and date | free |
| `list_sources` | The sources GridNews indexes, with ids for the `sources` filter | free |
| `get_topics` | Trending topic clusters as keyword groups with article counts | none |
| `get_usage` | The key's tier, entitlements, and remaining daily quota | free |
| `research` | Read documents or search results and return cited excerpts; `deep` also compares them | pro |
| `get_research` | Collect a research request that was still running when `research` returned | pro |

### Corroboration, not outlet count

`get_top_events` returns stories rather than documents, and reports two
different numbers:

- **`sourcesCount`** — how many outlets carried the story. This is reach.
- **`independent voices`** — how many of those were not republishing each
  other. This is the evidence.

They are usually not the same. Outlets that redistribute each other collapse
into one voice, so a story on five outlets all running the same wire copy is
one voice, not five. Where an outlet was carrying someone else's copy, the
tool marks it inline:

```
2 independent voices across 4 outlets · 4 filings · impact 1.47
- Wall Street Journal: https://wsj.com/...
- Dow Jones [carrying wall-street-journal]: https://morningstar.com/...
- GuruFocus: https://gurufocus.com/...
```

A press release is always a single voice however many wires carried it — one
issuer announcing itself is not confirmation.

Pass `minVoices: 2` for corroborated stories only. There is no default:
single-voice clusters are real distribution records and are not hidden, they
just rank last.

### Grid AI research

`research` reads up to 8 documents you name (`urls`), or searches the web or news
and reads the results, and returns the passages that bear on the query, quoted
verbatim and numbered for citation. `depth: "deep"` goes further: it compares the
sources and answers up to 3 `questions`, marking which statements are the
sources' and which are inference, and naming gaps and disagreements. A deep
request needs at least 3 sources, or 2 different URLs; below that it would be one
document paraphrased, which is not analysis.

```
# Grid AI research: Why was the export rule extended?
id sdk-4f1c... · deep · complete · 4 of 4 sources read · 38.2s

## Sources
[1] Commerce extends chip export rule
    reuters.com · 3h ago (2026-09-29T09:12:00Z, page date)
    https://reuters.com/...
    > The department said the extension gives ...

## Analysis: Why was the export rule extended?
Findings:
- Both reports tie the extension to the licensing review. [1][3]
- (inference) The timing suggests ... [2]
```

A quick request takes up to 90 seconds and a deep one up to 4 minutes. Many MCP
clients give up on a tool call after about a minute, so `research` waits
`waitSeconds` (default 50) and then returns what has arrived with the request
id. The request keeps running, and `get_research` collects it. Results are kept
for an hour. Clients that ask for progress get a notification per source, which
lets those that reset their timeout on progress wait for the whole request.

Research runs over the GridNews stream WebSocket and uses one of the key's stream
connections while it runs. Each key may run 2 requests at once on Pro and 4 on
Business, and research counts against the key's Grid AI allowance.

### Tier behaviour

GridNews gates features and history depth by tier. Rather than failing opaquely,
the tools report what a call needs:

- A 403 names the required tier and the key's current one, so the agent can
  retry without the gated parameter instead of giving up.
- A 429 reports remaining quota and reset time, so the agent waits rather than
  looping.
- Results note when a tier's history window excluded older articles, so a thin
  result isn't mistaken for an absence of coverage.

`get_usage` explains any of these on demand.

## Development

```bash
npm install
npm run build
npm test
```

The test suite drives the built server over a real stdio MCP session against a
stubbed API, so it covers protocol handshake, argument validation, HTTP
serialization, formatting, and the tier/quota failure paths without needing a
live key.

## License

MIT