# GovGreed MCP

GovGreed MCP is a [Model Context Protocol](https://modelcontextprotocol.io) server that gives Claude (and any MCP-aware client) native, one-line tool access to GovGreed's congressional-trading intelligence API. Ask Claude about a politician's conflict-of-interest score, today's A+ trading signals, which bills carve out money for a specific ticker, or how a company spends its political-influence dollars — and Claude answers from live GovGreed data instead of guessing. It wraps **18 tools** spanning signals, predictions, politicians, bills, companies, donors, and executive-branch (OGE) disclosures.

## Get an API key

Get a free API key at [govgreed.com](https://govgreed.com).

- **Free tier:** 100 calls/day for the first week, then 20/day.
- **Founders:** $24.50/mo = 750 calls/day, price locked forever.

Set it as the `GOVGREED_API_KEY` environment variable (shown in the install snippets below).

## Install

### uvx (recommended)

Add this to your MCP client config (e.g. `claude_desktop_config.json`) inside `"mcpServers"`:

```json
"govgreed": {
  "command": "uvx",
  "args": ["--from", "git+https://github.com/mmamodelai/govgreed-mcp", "govgreed-mcp"],
  "env": { "GOVGREED_API_KEY": "your_key" }
}
```

### Claude Code (one-liner)

```bash
claude mcp add govgreed --env GOVGREED_API_KEY=your_key -- uvx --from git+https://github.com/mmamodelai/govgreed-mcp govgreed-mcp
```

### pipx (alternative)

```bash
pipx install git+https://github.com/mmamodelai/govgreed-mcp
```

Then point your MCP client at the installed entry point:

```json
"govgreed": {
  "command": "govgreed-mcp",
  "env": { "GOVGREED_API_KEY": "your_key" }
}
```

## Tools

All 18 tools return a standard envelope with an `as_of` timestamp and a `data` payload.

| Tool | What it does |
|---|---|
| `account_info` | Show your current GovGreed account: tier, daily quota, remaining calls. |
| `top_signals` | Top-ranked congressional trading signals (7-layer convergence scoring); deduplicated per politician+ticker. |
| `herd_signals` | Moments when 3+ politicians converge on the same ticker, deduplicated per (ticker, window). |
| `whale_opportunities` | EV-ranked bills × tickers × insider activity, cross-checked against political influence to drop junk tickers. |
| `top_predictions` | Forward-looking predictions from GovGreed's four prediction engines, grouped per (politician, ticker). |
| `search_politicians` | Fuzzy politician search; resolves "Pelosi" → bioguide_id for follow-up calls. |
| `politician_profile` | Full politician profile with all four scores (greediness / influence / conflict / predicted-corruption). |
| `politician_conflict_score` | Conflict-of-interest score 0-100 — the most objective, vote-level evidence score. |
| `bill_intelligence` | Full bill baseball card: impacts, predictions, markup history, exec trades, carveouts. |
| `bill_carveouts` | Line-item carveouts: each $ amount tied to a recipient, section-cited, with ticker mapping. |
| `search_bills` | Fuzzy bill search by title or nickname (NDAA, CHIPS, IRA, etc.). |
| `company_profile` | Full company iron-triangle profile: congressional owners, lobbyists, affected-by bills, insider activity. |
| `company_political_influence` | 0-100 political influence score for a ticker, broken down by lobbying / contributions / pharma / LDA spend. |
| `sector_positioning` | Congressional buy/sell flow per sector over N days. |
| `search_donors` | Fuzzy donor search with fingerprint-aggregation across FEC name variants. |
| `search_donors_raw` | Raw FEC donor search — one row per name-string-as-filed, no merging. |
| `donor_profile` | Full donor profile, fingerprint-aggregated, with deduplicated recent gifts. |
| `oge_cabinet_trades` | Trump-administration cabinet/senior-WH-staff financial disclosures and transactions (OGE 278e + 278-T). |

## Score-name semantics

> GovGreed surfaces **four different scores** on a politician. They measure
> different things and should not be compared 1:1 — pick the right one:
>
> - **greediness** — Behavioral: how aggressively they trade (volume × frequency × recency). High = active trader, not necessarily corrupt. (Pelosi ≈ 44.)
> - **influence_score** — Structural: how much money/lobbying flows *to* them (donor flows, lobbying alignment, PAC industry tags). High = well-funded. (Pelosi ≈ 90.)
> - **conflict_score** — Vote-level: bills they voted YES on while holding affected stock, weighted by impact and timing. Subscores: trade_activity, late_filing, committee_alignment, donor_alignment, voted_holdings. (Pelosi ≈ 22.)
> - **predicted_corruption_risk** — Forward-looking ML score from the LLM behavioral analysis. (Pelosi ≈ 85.)
>
> "How concerning is X right now" → **conflict_score** (most objective). "How active is their trading" → **greediness**. "Structural pull in DC" → **influence_score**.

## Donor fingerprinting

The FEC stores donor names as filed, so one person fractures into many records — e.g. Robert L. Mercer appears as `MERCER, ROBERT L.`, `MERCER, ROBERT MR.`, `MERCER, ROBERT L`, `MERCER, ROBERT L. MR.`, `MERCER, ROBERT L MR` (~$4.66M combined). `search_donors` / `donor_profile` return **fingerprinted** records that merge variants by canonical name + state + employer, with `variants_merged`, `match_method`, and `match_confidence` on every result. Use `search_donors_raw` to see the unmerged FEC name strings. Merging is deliberately *not* done across different employer, different state, or different generational suffix (JR vs SR is preserved).

## Example prompts

Paste any of these into Claude once the server is connected:

- "What are today's A+ congressional signals?"
- "What's Pelosi's conflict score and why?"
- "Which bills have carveouts for $NVDA?"

---

Not financial advice. Data from public federal disclosures.