convez.ai
MCP ServerFinanceiroIntermediário
hanlulong

OpenEcon Data

hanlulong/openecon-data

330K indicadores econômicos oficiais para agentes de IA — sem alucinações

Ver no GitHub
BomPluginScore · de 0 a 100

MCP server que conecta agentes de IA a 330 mil indicadores econômicos de fontes oficiais (FRED, Banco Mundial, FMI, Eurostat e mais). Elimina alucinações de dados ao fornecer informações verificadas, atualizadas em tempo real e com atribuição de fonte para análises econômicas precisas.

Instalação

$npx convez-ai hanlulong/openecon-data

1 comando no terminal: detecta o formato do repositório (marketplace ou plugin avulso) e instala via Claude Code. Requer Node 18+ e o Claude Code instalado.

Métricas

Estrelas
93
Forks
15
Acompanhando
2
Saúde
71%
Último commit
há 2 dias
Versão
—
Issues abertas
0
Contribuidores
1

Casos de uso

  • Análise macroeconômica com dados em tempo real
  • Comparações econômicas entre países e períodos
  • Pesquisa financeira e de mercado com fontes verificadas
  • Automação de relatórios econômicos com dados atualizados

Veredito

MCP server robusto que resolve um problema real: alucinações em dados econômicos. Integração direta com agentes Claude, cobertura abrangente de fontes oficiais e interface amigável. Produção-ready com demo funcional.

README

A tradução para o português deste README ainda está na fila.


Install (One Line, Then Just Talk)

curl -fsSL https://raw.githubusercontent.com/hanlulong/openecon-data/main/scripts/install.sh | bash

That's it. The script auto-detects Claude Code and Codex, configures everything. Then just ask:

You: "What's the US GDP growth rate?"         → your agent fetches real data from FRED
You: "Compare inflation across G7 countries"   → World Bank data for 7 countries
You: "Bitcoin price last 30 days"              → CoinGecko live data

No special syntax. No "use query_data". Just ask naturally — your agent handles the rest.

Claude Code:

claude mcp add --transport sse openecon-data https://data.openecon.ai/mcp --scope user

Codex:

codex mcp add openecon-data --url https://data.openecon.ai/mcp

Any MCP agent: Endpoint https://data.openecon.ai/mcp (SSE transport)

See skills/README.md for slash commands and auto-trigger options.


Why Your Agent Needs This

AI agents hallucinate economic data. When you ask an LLM "What is US GDP?", you get a plausible-sounding number that may be outdated or wrong. OpenEcon solves this:

Without OpenEconWith OpenEcon
Data sourceLLM's training data (stale)Official APIs (FRED, World Bank, IMF)
AccuracyApproximate, often wrongVerified, with source attribution
CoverageWhatever the LLM remembers330K+ indicators, 200+ countries
RecencyMonths or years behindUp to real-time (FRED, ExchangeRate)
VerifiableNo source linkEvery result includes source URL

How It Compares

FeatureOpenEconfredapipandas-datareaderfred-mcp-server
Natural language queriesYesNoNoNo
Data sources10+1 (FRED)51 (FRED)
MCP server for AI agentsYesNoNoYes
Web UI with chartsYesNoNoNo
Conversational follow-upsYesNoNoNo
Smart indicator discovery330K indexedManual codesManual codesManual codes
Self-hostableYesN/AN/AYes
No code requiredYesNoNoNo

What You Can Ask

"US GDP growth last 10 years"                    → FRED, quarterly chart
"Compare China, India, Brazil GDP 2018-2024"     → World Bank, multi-country comparison
"Inflation rate BRICS countries 2019-2023"        → World Bank, 5 countries auto-expanded
"EUR/USD exchange rate last 24 months"            → ExchangeRate-API, currency pair chart
"US unemployment and CPI together since 2010"     → FRED, dual-axis overlay
"China exports to the US 2020-2024"               → UN Comtrade, bilateral trade flow
"Credit to GDP ratio US, UK, Japan from BIS"      → BIS, financial stability data
"Bitcoin price last year"                         → CoinGecko, crypto chart
"What inflation indicators does FRED have?"       → Indicator discovery, text response

Conversational follow-ups work naturally:

You: "US GDP last 5 years"          → chart with US GDP
You: "add Germany and Japan"         → updates to 3 countries
You: "what about per capita?"        → switches to GDP per capita
You: "show only 2020-2023"           → narrows time range

Quick Start

Use the web app (no setup)

data.openecon.ai/chat — try instantly in your browser, no install. Your first 20 queries need no signup. Create a free account (email or Google) to keep going, save your history, and unlock Pro Mode.

Self-host

git clone https://github.com/hanlulong/openecon-data.git
cd openecon-data
./scripts/setup.sh            # Installs npm + Python deps, creates backend/.venv, copies .env.example → .env

Then edit .env and set the two values the backend needs to start:

OPENROUTER_API_KEY=sk-or-...                  # required (LLM parsing) — https://openrouter.ai/keys
JWT_SECRET=...                                # required — generate with: openssl rand -hex 32

Start both servers:

python3 scripts/restart_dev.py
# Backend: http://localhost:3001  |  Frontend: http://localhost:5173

Then ask your first question — plain English in, sourced data out:

curl -X POST http://localhost:3001/api/query \
  -H "Content-Type: application/json" \
  -d '{"query": "US unemployment rate since 2023"}'
{
  "data": [{
    "metadata": {
      "source": "FRED",
      "indicator": "Unemployment Rate",
      "unit": "Percent",
      "sourceUrl": "https://fred.stlouisfed.org/series/UNRATE"  // every result links to its source
    },
    "data": [{ "date": "2023-01", "value": 3.4 }, /* ... */]
  }]
}
npm install
python3 -m venv backend/.venv
source backend/.venv/bin/activate            # Windows: backend\.venv\Scripts\activate
pip install --upgrade pip
pip install -r backend/requirements.txt
cp .env.example .env                         # then set OPENROUTER_API_KEY and JWT_SECRET
python3 scripts/restart_dev.py
  • Python 3.10+
  • Node.js 18+
  • Required to start the backend:
    • OPENROUTER_API_KEY — OpenRouter API key for LLM parsing (required unless you set LLM_PROVIDER to a local model like vllm/ollama/lm-studio)
    • JWT_SECRET — any random secret; generate with openssl rand -hex 32
  • Optional: FRED API key, Comtrade API key, CoinGecko API key
  • Optional: Supabase credentials (enables real auth, Google sign-in, and persistent history; mock auth is used in development when omitted)

See Getting Started Guide for full setup instructions.

How It Works

  "Compare US and           ┌──────────────┐        ┌────────────────┐
   Japan inflation"    ───▶ │  LLM Parser  │  ───▶  │  LLM Router    │
                            │  (intent,    │        │  (semantic      │
                            │   countries, │        │   routing +     │
                            │   dates)     │        │   330K index)   │
                            └──────────────┘        └───────┬────────┘
                                                            │
                            ┌────────────┐          ┌───────▼────────┐
                            │ Chart +    │  ◀────── │  Fetch from    │
                            │ CSV/JSON/  │          │  best provider │
                            │ DTA/Python │          │  (FRED, WB,    │
                            └────────────┘          │   IMF, ...)    │
                                                    └────────────────┘
  1. Parse — An LLM extracts intent, countries, indicators, and date range from plain English
  2. Route — Semantic routing picks the best provider and series from 330K+ indicators
  3. Fetch — Data retrieved from official APIs with automatic fallback if a source is down
  4. Return — Interactive chart, or structured data via MCP for your agent

Features

MCP Server — First-class Model Context Protocol support. Give Claude Code, Codex, or any MCP-compatible agent access to verified economic data.

Natural Language — No API docs, no country codes, no series IDs. Just describe what you want.

330K Indicator Discovery — Full-text search across FRED, World Bank, IMF, Eurostat, BIS, and more. Ask "What trade data does Comtrade have?" and get a browsable list.

Multi-Round Conversations — Follow up naturally: add countries, change time ranges, switch indicators. Context is preserved across turns, so "now add Germany" just works.

Smart Routing — The system understands what you mean, not just what you type. It picks the right provider (FRED for US data, World Bank for global comparisons, Comtrade for trade flows) based on the meaning of your query.

Multi-Country Comparisons — Say "G7", "BRICS", "EU", "ASEAN", "Nordic" or list specific countries. Auto-expands to all members.

Fast — Repeat queries return in ~0.1 seconds. First-time queries take ~4 seconds end-to-end.

Resilient — If one provider is down, the system automatically falls back to the next-best source. No manual retries needed.

Clarifies Ambiguity — When a query could mean multiple things ("inflation" could be CPI, PCE, or GDP deflator), the system asks you to pick rather than guessing wrong.

Multi-Format Export — CSV, JSON, DTA (Stata), and Python code. Every export includes source attribution.

Pro Mode — AI-generated Python for advanced analysis: custom transformations, derived indicators, bespoke charts. Available to registered users on the hosted app. Disabled by default when self-hosting; set PROMODE_ENABLED=true only with proper sandboxing, since it executes generated code.

Streaming — Real-time progress via Server-Sent Events.

Accounts & Auth — Try the first 20 queries with no signup. Sign in with email + password or Google to save history and unlock Pro Mode. Includes email verification, password reset, and JWT-based sessions. Authentication is backed by Supabase (with a local mock-auth fallback for development).

Self-Hostable — AGPL-3.0 licensed. Add new providers by implementing a single base class.

Performance

MetricValue
First query~4.3s end-to-end
Repeat query (cached)~0.1s
Indicator database330,000+ indexed series across 10 providers

Data Sources

10 providers, 330K+ indexed indicators:

ProviderCoverageIndicatorsAPI Key
FREDUS macroeconomic data (GDP, CPI, employment, rates)90,000+ seriesFree
World BankGlobal development (200+ countries, poverty, health)16,000+ indicatorsNone
IMFBalance of payments, exchange rates, fiscal dataExtensiveNone
EurostatEU member states (HICP, labor, trade)ExtensiveNone
UN ComtradeBilateral trade flows by HS commodity codeAll HS codesFree
BISCredit-to-GDP, property prices, debt securitiesCuratedNone
Statistics CanadaCanadian economic tables (labor, trade, prices)40,000+ tablesNone
OECDOECD member country statisticsExtensiveNone
ExchangeRate-API160+ currency pairs, live and historicalLive & historicalFree
CoinGeckoCryptocurrency prices and market data10,000+ coinsFree

Who Is This For?

RoleHow they use it
AI Agent BuildersAdd economic data capabilities to any MCP-compatible agent — verified data, not hallucinations
Economists & ResearchersQuick data pulls for papers without writing API code
Policy AnalystsCross-country comparisons (G7, BRICS, EU) with one query
StudentsLearn by exploring — ask questions, see data, export for assignments
JournalistsFact-check economic claims against official sources in seconds

Architecture

┌─────────────────┐     ┌──────────────────┐     ┌──────────────────────────┐
│  User / Agent   │────▶│  FastAPI Backend  │────▶│  Data Providers          │
│                 │     │                  │     │                          │
│  "US inflation" │     │  LLM Parser      │     │  FRED · World Bank · IMF │
│                 │◀────│  LLM Router      │◀────│  Eurostat · BIS · ...    │
│  Chart + Data   │     │  330K Index      │     │                          │
└─────────────────┘     └──────────────────┘     └──────────────────────────┘
        │                        │
   React Frontend          MCP Endpoint
   (Vite + Recharts)     (SSE Transport)

Stack: Python · FastAPI · React · TypeScript · Vite · Recharts · Redis · OpenRouter

Contributing

Contributions welcome! See the Developer & Contributor Guide.

If you find this useful, a star helps others discover the project.

License

AGPL-3.0 — Free to use, modify, and self-host. If you run a modified version as a service, you must share your changes. For commercial licensing, contact us.

Ver o original no GitHub

Bom para

Relacionados