OpenEcon Data

1<p align="center">
2  <img src="packages/frontend/public/favicon.svg" width="80" height="80" alt="OpenEcon logo" />
3</p>
4 
5<h1 align="center">OpenEcon Data</h1>
6 
7<p align="center">
8  <strong>Give your AI agent accurate economic data.</strong><br/>
9  330K indicators from FRED, World Bank, IMF, Eurostat, and 6 more sources — one MCP command away.
10</p>
11 
12<p align="center">
13  <a href="https://data.openecon.ai/chat"><img src="https://img.shields.io/badge/Try_it-Live_Demo-blue?style=flat-square" alt="Live Demo" /></a>
14  <a href="LICENSE"><img src="https://img.shields.io/badge/License-AGPL--3.0-blue?style=flat-square" alt="AGPL-3.0 License" /></a>
15  <a href="https://github.com/hanlulong/openecon-data/stargazers"><img src="https://img.shields.io/github/stars/hanlulong/openecon-data?style=flat-square" alt="Stars" /></a>
16  <a href="https://github.com/hanlulong/openecon-data/issues"><img src="https://img.shields.io/github/issues/hanlulong/openecon-data?style=flat-square" alt="Issues" /></a>
17  <img src="https://img.shields.io/badge/Python-3.10+-blue?style=flat-square&logo=python&logoColor=white" alt="Python" />
18  <img src="https://img.shields.io/badge/MCP-Server-purple?style=flat-square" alt="MCP Server" />
19  <img src="https://img.shields.io/github/last-commit/hanlulong/openecon-data?style=flat-square" alt="Last Commit" />
20</p>
21 
22<p align="center">
23  <a href="https://openecon.ai">Website</a> &middot;
24  <a href="https://data.openecon.ai/chat">Live App</a> &middot;
25  <a href="docs/README.md">Docs</a> &middot;
26  <a href="docs/development/DEVELOPER_CONTRIBUTOR_GUIDE.md">Contributing</a>
27</p>
28 
29---
30 
31## Install (One Line, Then Just Talk)
32 
33```bash
34curl -fsSL https://raw.githubusercontent.com/hanlulong/openecon-data/main/scripts/install.sh | bash
35```
36 
37That's it. The script auto-detects Claude Code and Codex, configures everything. Then just ask:
38 
39```
40You: "What's the US GDP growth rate?"         → your agent fetches real data from FRED
41You: "Compare inflation across G7 countries"   → World Bank data for 7 countries
42You: "Bitcoin price last 30 days"              → CoinGecko live data
43```
44 
45No special syntax. No "use query_data". Just ask naturally — your agent handles the rest.
46 
47<details>
48<summary><b>Manual install (if you prefer)</b></summary>
49 
50**Claude Code:**
51```bash
52claude mcp add --transport sse openecon-data https://data.openecon.ai/mcp --scope user
53```
54 
55**Codex:**
56```bash
57codex mcp add openecon-data --url https://data.openecon.ai/mcp
58```
59 
60**Any MCP agent:** Endpoint `https://data.openecon.ai/mcp` (SSE transport)
61 
62See [skills/README.md](skills/README.md) for slash commands and auto-trigger options.
63</details>
64 
65---
66 
67<p align="center">
68  <img src="docs/assets/demo.gif" width="800" alt="OpenEcon Data — type a query in plain English, get a chart with data from FRED, World Bank, and more" />
69</p>
70 
71## Why Your Agent Needs This
72 
73AI 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:
74 
75| | Without OpenEcon | With OpenEcon |
76|---|---|---|
77| **Data source** | LLM's training data (stale) | Official APIs (FRED, World Bank, IMF) |
78| **Accuracy** | Approximate, often wrong | Verified, with source attribution |
79| **Coverage** | Whatever the LLM remembers | 330K+ indicators, 200+ countries |
80| **Recency** | Months or years behind | Up to real-time (FRED, ExchangeRate) |
81| **Verifiable** | No source link | Every result includes source URL |
82 
83## How It Compares
84 
85| Feature | OpenEcon | fredapi | pandas-datareader | fred-mcp-server |
86|---------|----------|---------|-------------------|-----------------|
87| Natural language queries | Yes | No | No | No |
88| Data sources | 10+ | 1 (FRED) | 5 | 1 (FRED) |
89| MCP server for AI agents | Yes | No | No | Yes |
90| Web UI with charts | Yes | No | No | No |
91| Conversational follow-ups | Yes | No | No | No |
92| Smart indicator discovery | 330K indexed | Manual codes | Manual codes | Manual codes |
93| Self-hostable | Yes | N/A | N/A | Yes |
94| No code required | Yes | No | No | No |
95 
96## What You Can Ask
97 
98```
99"US GDP growth last 10 years"                    → FRED, quarterly chart
100"Compare China, India, Brazil GDP 2018-2024"     → World Bank, multi-country comparison
101"Inflation rate BRICS countries 2019-2023"        → World Bank, 5 countries auto-expanded
102"EUR/USD exchange rate last 24 months"            → ExchangeRate-API, currency pair chart
103"US unemployment and CPI together since 2010"     → FRED, dual-axis overlay
104"China exports to the US 2020-2024"               → UN Comtrade, bilateral trade flow
105"Credit to GDP ratio US, UK, Japan from BIS"      → BIS, financial stability data
106"Bitcoin price last year"                         → CoinGecko, crypto chart
107"What inflation indicators does FRED have?"       → Indicator discovery, text response
108```
109 
110**Conversational follow-ups work naturally:**
111```
112You: "US GDP last 5 years"          → chart with US GDP
113You: "add Germany and Japan"         → updates to 3 countries
114You: "what about per capita?"        → switches to GDP per capita
115You: "show only 2020-2023"           → narrows time range
116```
117 
118## Quick Start
119 
120### Use the web app (no setup)
121 
122**[data.openecon.ai/chat](https://data.openecon.ai/chat)** — no signup, no install.
123 
124### Self-host
125 
126```bash
127git clone https://github.com/hanlulong/openecon-data.git
128cd openecon-data
129cp .env.example .env          # Add your OPENROUTER_API_KEY
130pip install -r requirements.txt
131npm install
132python3 scripts/restart_dev.py
133# Backend: http://localhost:3001  |  Frontend: http://localhost:5173
134```
135 
136<details>
137<summary><b>Requirements</b></summary>
138 
139- Python 3.10+
140- Node.js 18+
141- An [OpenRouter API key](https://openrouter.ai/keys) (required for LLM parsing)
142- Optional: FRED API key, Comtrade API key, CoinGecko API key
143- Optional: Supabase credentials (for auth + persistent history)
144 
145See [Getting Started Guide](docs/guides/getting-started.md) for full setup instructions.
146</details>
147 
148## How It Works
149 
150```
151  "Compare US and           ┌──────────────┐        ┌────────────────┐
152   Japan inflation"    ───▶ │  LLM Parser  │  ───▶  │  Smart Router  │
153                            │  (intent,    │        │  (67 curated   │
154                            │   countries, │        │   concepts +   │
155                            │   dates)     │        │   330K index)  │
156                            └──────────────┘        └───────┬────────┘
157                                                            │
158                            ┌────────────┐          ┌───────▼────────┐
159                            │ Chart +    │  ◀────── │  Fetch from    │
160                            │ CSV/JSON/  │          │  best provider │
161                            │ DTA/Python │          │  (FRED, WB,    │
162                            └────────────┘          │   IMF, ...)    │
163                                                    └────────────────┘
164```
165 
1661. **Parse** — An LLM extracts intent, countries, indicators, and date range from plain English
1672. **Route** — 67 curated economic concepts + 330K indicator index picks the best provider
1683. **Fetch** — Data retrieved from official APIs, normalized and aligned
1694. **Return** — Interactive chart, or structured data via MCP for your agent
170 
171## Features
172 
173**MCP Server** — First-class [Model Context Protocol](https://modelcontextprotocol.io) support. Give Claude Code, Codex, or any MCP-compatible agent access to verified economic data.
174 
175**Natural Language** — No API docs, no country codes, no series IDs. Just describe what you want.
176 
177**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.
178 
179**Conversational** — Follow up naturally: add countries, change time ranges, switch indicators. The system remembers context.
180 
181**Multi-Country Comparisons** — Say "G7", "BRICS", "EU", "ASEAN", "Nordic" or list specific countries. Auto-expands to all members.
182 
183**67 Curated Concepts** — Hand-verified mappings ensure "US jobless claims" routes to FRED/ICSA, not a generic unemployment rate.
184 
185**Cross-Encoder Reranking** — FlashRank reranks search results so "GDP growth rate" matches the growth series, not raw GDP levels. Retrieve broadly, rerank precisely.
186 
187**Multi-Format Export** — CSV, JSON, DTA (Stata), and Python code. Every export includes source attribution.
188 
189**Streaming** — Real-time progress via Server-Sent Events.
190 
191**Self-Hostable** — AGPL-3.0 licensed. Add new providers by implementing a single base class.
192 
193## Data Sources
194 
195| Provider | Coverage | Indicators | API Key |
196|----------|----------|-----------|---------|
197| **FRED** | US macroeconomic data | 90,000+ series | Free |
198| **World Bank** | Global development | 16,000+ indicators | None |
199| **IMF** | International financial statistics | Extensive | None |
200| **Eurostat** | EU member states | Extensive | None |
201| **UN Comtrade** | International trade flows | All HS codes | Free |
202| **BIS** | Central bank & financial stability | Curated | None |
203| **Statistics Canada** | Canadian economic data | 40,000+ tables | None |
204| **OECD** | OECD member countries | Extensive | None |
205| **ExchangeRate-API** | 160+ currencies | Live & historical | Free |
206| **CoinGecko** | Cryptocurrencies | 10,000+ coins | Free |
207 
208## Who Is This For?
209 
210| Role | How they use it |
211|------|----------------|
212| **AI Agent Builders** | Add economic data capabilities to any MCP-compatible agent — verified data, not hallucinations |
213| **Economists & Researchers** | Quick data pulls for papers without writing API code |
214| **Policy Analysts** | Cross-country comparisons (G7, BRICS, EU) with one query |
215| **Students** | Learn by exploring — ask questions, see data, export for assignments |
216| **Journalists** | Fact-check economic claims against official sources in seconds |
217 
218## Architecture
219 
220```
221┌─────────────────┐     ┌──────────────────┐     ┌──────────────────────────┐
222│  User / Agent   │────▶│  FastAPI Backend  │────▶│  Data Providers          │
223│                 │     │                  │     │                          │
224│  "US inflation" │     │  LLM Parser      │     │  FRED · World Bank · IMF │
225│                 │◀────│  Query Router    │◀────│  Eurostat · BIS · ...    │
226│  Chart + Data   │     │  Normalizer      │     │                          │
227└─────────────────┘     └──────────────────┘     └──────────────────────────┘
228        │                        │
229   React Frontend          MCP Endpoint
230   (Vite + Recharts)     (SSE Transport)
231```
232 
233**Stack:** Python · FastAPI · React · TypeScript · Vite · Recharts · FAISS · OpenRouter
234 
235## Contributing
236 
237Contributions welcome! See the [Developer & Contributor Guide](docs/development/DEVELOPER_CONTRIBUTOR_GUIDE.md).
238 
239- [Open issues](https://github.com/hanlulong/openecon-data/issues) — bug reports and feature requests
240- [Documentation](docs/README.md) — full docs index
241- [Security policy](.github/SECURITY.md) — responsible disclosure
242 
243If you find this useful, a star helps others discover the project.
244 
245## License
246 
247[AGPL-3.0](LICENSE) — 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](mailto:security@openecon.ai).
248