# Heron Intelligence MCP

Heron Intelligence — Financial Research MCP server for AI assistants.

Connect Heron Intelligence's financial research capabilities (earnings call transcripts,
due diligence interviews, red flag analysis) directly to Claude, Cursor,
or any MCP-compatible client.

## Requirements

- An active Heron Intelligence account with an API key
- `uvx` (no other installation needed)

## Installation

### Claude Desktop

Add to `~/.claude/claude_desktop_config.json`:

```json
{
  "mcpServers": {
    "heron": {
      "command": "uvx",
      "args": ["--from", "HeronIntelligence-mcp", "heronintelligence-mcp"],
      "env": {
        "HERON_API_KEY": "heron-key-xxxx"
      }
    }
  }
}
```

Restart Claude Desktop. Heron Intelligence will appear as an active tool.

### Claude Code

```bash
claude mcp add heron \
  --command uvx \
  --args "--from HeronIntelligence-mcp heronintelligence-mcp" \
  -e HERON_API_KEY=heron-key-xxxx \
  -s user
```

### Cursor / Windsurf

Add to your MCP config:

```json
{
  "mcpServers": {
    "heron": {
      "command": "uvx",
      "args": ["--from", "HeronIntelligence-mcp", "heronintelligence-mcp"],
      "env": {
        "HERON_API_KEY": "heron-key-xxxx"
      }
    }
  }
}
```

## Available Tools

| Tool | Description |
| --- | --- |
| `search_company` | Find a company by name, ticker, or description |
| `get_recent_transcripts` | List transcripts for a company over the last N quarters |
| `analyze_red_flags` | Deep risk analysis with citations — powered by Heron Intelligence's ReAct agent |
| `get_transcript_content` | Fetch full transcript content by ID |

## Example Queries

Once connected, ask your AI assistant:

> *"What are the red flags for Rappi in the last 3 quarters?"*
> *"What is Nubank's management saying about churn this year?"*
> *"Compare the tone of Mercado Libre vs Kavak interviewees"*
> *"Executive summary of the last 3 earnings calls for {company}"*

## Billing Tiers

| Tier | Monthly | API Calls | Agent Calls (`analyze_red_flags`) | RPM | Data Window |
| --- | --- | --- | --- | --- | --- |
| Trial | Free (14d) | 100 | 10 | 5 | Last 2 quarters |
| Starter | $199 | 500 | 50 | 10 | Last 4 quarters |
| Professional | $499 | 2,000 | 200 | 30 | Last 8 quarters |
| Enterprise | Custom | Unlimited | Custom | 100 | Full history |

`analyze_red_flags` counts as both 1 API call and 1 agent call.

## Quota Errors

When your quota is exhausted the tool returns a human-readable message:

```
Heron Intelligence quota limit reached: Monthly request quota exhausted.
Your quota resets at 2026-04-01T00:00:00+00:00.
```

The API also sets response headers you can inspect:

| Header | Meaning |
| --- | --- |
| `X-RateLimit-Limit-Minute` | Requests allowed per minute |
| `X-Quota-Requests-Remaining` | Requests left this month |
| `X-Quota-Reset` | ISO timestamp when the monthly counter resets |
| `Retry-After` | Seconds to wait (RPM 429 only) |

## Environment Variables

| Variable | Description |
| --- | --- |
| `HERON_API_KEY` | Your Heron Intelligence API key (from your account dashboard) |
| `HERON_TIMEOUT` | HTTP timeout in seconds (default: `120.0`) |

## License

Proprietary — requires an active Heron Intelligence subscription.
