Metadata-Version: 2.4
Name: econewsapi-mcp
Version: 0.7.0
Summary: MCP server for econewsapi — surface Brazilian financial news to Claude/AI agents
Project-URL: Homepage, https://github.com/economatica/EcoNewsApi-MCP
Project-URL: Repository, https://github.com/economatica/EcoNewsApi-MCP
Project-URL: Issues, https://github.com/economatica/EcoNewsApi-MCP/issues
Project-URL: Changelog, https://github.com/economatica/EcoNewsApi-MCP/releases
Author: Economatica
License: MIT
Keywords: ai,b3,brazil,claude,finance,mcp,news
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Financial and Insurance Industry
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Office/Business :: Financial
Classifier: Topic :: Office/Business :: News/Diary
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.10
Requires-Dist: httpx>=0.27.0
Requires-Dist: mcp>=1.0.0
Provides-Extra: dev
Requires-Dist: pytest-asyncio>=0.23; extra == 'dev'
Requires-Dist: pytest>=8.0; extra == 'dev'
Requires-Dist: ruff>=0.5; extra == 'dev'
Description-Content-Type: text/markdown

# econewsapi-mcp

MCP server that exposes Brazilian financial news from [econewsapi](https://news-api.economatica.com)
to Claude Desktop, Claude Code, and other [Model Context Protocol](https://modelcontextprotocol.io)
compatible AI agents.

## What it does

Lets you (or your AI agent) talk to econewsapi in natural language:

> "Como tá o setor de petróleo hoje?"
> "Tem fato relevante novo da Vale?"
> "Quem foram os tickers mais comentados ontem?"
> "Sumarize os resultados anuais dos bancos"

Behind the scenes the agent picks the right tool, calls the API with
HMAC-signed requests, and synthesizes a response.

## Tools (v0.5.0)

| Tool | What it does |
|---|---|
| `search_news` | Filter news by ticker / source / channel / scores / time window |
| `get_news` | Full content + summary + entities for one news item |
| `trending_tickers` | B3 tickers with highest news velocity |
| `list_sectors` | All B3 sectors (energy, financials, ...) with PT labels |
| `list_tickers_by_sector` | Resolve a sector to its B3 tickers (use before `search_news`) |
| `list_topics` | Curated news topics (commodities, dividends, M&A, ...) |
| `sentiment_overview` | Aggregate positive/negative/neutral counts for any filter slice |
| `sentiment_trend` | Sentiment evolution over time (bucketed) — improving/worsening detection |
| `upcoming_events` | Calendar of upcoming events: COPOM decisions, Brazilian earnings (DFP/ITR), monetary reports |
| `get_event` | Full detail of a single calendar event (incl. AI enrichment fields when available) |

More tools coming: `get_related_news`, `news_price_impact`.

## Install

```bash
pip install econewsapi-mcp
```

Or run directly without installing:

```bash
uvx econewsapi-mcp
```

## Configure (Claude Desktop)

Edit `~/Library/Application Support/Claude/claude_desktop_config.json`:

```json
{
  "mcpServers": {
    "economatica": {
      "command": "uvx",
      "args": ["econewsapi-mcp"],
      "env": {
        "ECONEWSAPI_API_KEY": "your-api-key",
        "ECONEWSAPI_API_SECRET": "your-api-secret"
      }
    }
  }
}
```

Restart Claude Desktop. Open a chat — the 🔧 icon should show
`Economatica News` as a connected server.

> **Note**: the package name (`econewsapi-mcp`) and the env vars
> (`ECONEWSAPI_*`) keep the legacy `econewsapi` prefix for backward
> compatibility. The display name and config key (`economatica`)
> reflect the parent brand.

## Configure (Claude Code)

Add the same `mcpServers` block to `~/.claude/settings.json` (or
`.claude/settings.json` in a project) and restart Claude Code.

## Updating

`uvx` caches packages aggressively — a Claude Desktop restart alone won't
pick up a new release. Three ways to upgrade:

**Option A — Pin the version (recommended for prod):**

```json
"args": ["econewsapi-mcp@0.5.0"]
```

Edit the JSON each time you bump. Deterministic — no cache surprises.

**Option B — Always-fresh (dev-friendly, ~1-2s cold start cost):**

```json
"args": ["--refresh", "econewsapi-mcp"]
```

`uvx` checks PyPI for newer versions on every Claude Desktop launch.

**Option C — One-shot manual refresh** (keep config simple):

```bash
uvx --refresh econewsapi-mcp --help
# or just bust the cache:
uv cache clean econewsapi-mcp
```

Then restart Claude Desktop. Next launch picks up the new version.

If you installed via `uv tool install`:

```bash
uv tool upgrade econewsapi-mcp
```

If you installed via `pip` in a venv:

```bash
pip install --upgrade econewsapi-mcp
```

## Configure (dev / local source)

```json
{
  "mcpServers": {
    "econewsapi": {
      "command": "uvx",
      "args": ["--from", "/abs/path/to/EcoNewsApi-MCP", "econewsapi-mcp"],
      "env": { "ECONEWSAPI_API_KEY": "...", "ECONEWSAPI_API_SECRET": "..." }
    }
  }
}
```

## Environment variables

| name | required | default |
|---|---|---|
| `ECONEWSAPI_API_KEY` | yes | — |
| `ECONEWSAPI_API_SECRET` | yes | — |
| `ECONEWSAPI_BASE_URL` | no | `https://news-api.economatica.com` |
| `ECONEWSAPI_LOG_LEVEL` | no | `INFO` |

## Development

```bash
git clone <this-repo>
cd EcoNewsApi-MCP
python3 -m venv .venv && source .venv/bin/activate
pip install -e ".[dev]"

# run smoke test against prod (requires test API key)
export ECONEWSAPI_API_KEY=...
export ECONEWSAPI_API_SECRET=...
pytest tests/ -v

# run the MCP server manually to inspect stdio output
econewsapi-mcp
```

## License

MIT
