Skip to content
Back to search

openecon-data

Give your AI agent accurate economic data. 330K indicators from FRED, World Bank, IMF, Eurostat & more. MCP server + web UI.

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today

Check it deeper on your machine

It has changed since its scan on 11 Nov 2026.

As a Claude Code plugin, install it and then ask Claude Code:

/plugin marketplace add keithmackay/mackayi/plugin install scanskillsafety@mackayiDo a deep scan of https://github.com/hanlulong/openecon-data with scanskillsafety

Or from a terminal, clone it and run it:

git clone https://github.com/keithmackay/scanskillsafety-skill ~/.claude/skills/scanskillsafetynode ~/.claude/skills/scanskillsafety/cli.cjs --deep 'https://github.com/hanlulong/openecon-data'

It checks the exact commit: every file, its packages against OSV (api.osv.dev), how it compares with this page's scan (findsafeskills.com receives the repository's address), and, if you agree, Claude reading every file with your own Claude subscription. It never runs the code.

Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/hanlulong--openecon-data/badge.svg)](/listings/hanlulong--openecon-data)

HTML

<a href="/listings/hanlulong--openecon-data"><img src="/api/listings/hanlulong--openecon-data/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

These steps run a script from the network that findsafeskills does not scan.

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.

<details> <summary><b>Manual install (if you prefer)</b></summary>

**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](skills/README.md) for slash commands and auto-trigger options. </details>

---

<p align="center"> </p>

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 345 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

This file has changed since it was scanned, so this is not exactly the text that was scanned, and no line is marked. The findings are listed with the safety scan above.

  1. <p align="center">
  2. <img src="packages/frontend/public/favicon.svg" width="80" height="80" alt="OpenEcon logo" />
  3. </p>
  4. <h1 align="center">OpenEcon Data</h1>
  5. <p align="center">
  6. <strong>Give your AI agent accurate economic data.</strong><br/>
  7. 330K indicators from FRED, World Bank, IMF, Eurostat, and 7 more sources — one MCP command away.
  8. </p>
  9. <p align="center">
  10. <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>
  11. <a href="LICENSE"><img src="https://img.shields.io/badge/License-AGPL--3.0-blue?style=flat-square" alt="AGPL-3.0 License" /></a>
  12. <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>
  13. <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>
  14. <img src="https://img.shields.io/badge/Python-3.10+-blue?style=flat-square&logo=python&logoColor=white" alt="Python" />
  15. <img src="https://img.shields.io/badge/MCP-Server-purple?style=flat-square" alt="MCP Server" />
  16. <img src="https://img.shields.io/github/last-commit/hanlulong/openecon-data?style=flat-square" alt="Last Commit" />
  17. </p>
  18. <p align="center">
  19. <a href="https://openecon.ai">Website</a> &middot;
  20. <a href="https://data.openecon.ai/chat">Live App</a> &middot;
  21. <a href="docs/README.md">Docs</a> &middot;
  22. <a href="docs/reference/api.md">API Reference</a> &middot;
  23. <a href="docs/development/DEVELOPER_CONTRIBUTOR_GUIDE.md">Contributing</a>
  24. </p>
  25. <p align="center">
  26. <a href="README.md">English</a> &middot;
  27. <a href="README.zh-CN.md">简体中文</a>
  28. </p>
  29. ---
  30. ## Install (One Line, Then Just Talk)
  31. ```bash
  32. curl -fsSL https://raw.githubusercontent.com/hanlulong/openecon-data/main/scripts/install.sh | bash
  33. ```
  34. That's it. The script auto-detects Claude Code and Codex, configures everything. Then just ask:
  35. ```
  36. You: "What's the US GDP growth rate?" → your agent fetches real data from FRED
  37. You: "Compare inflation across G7 countries" → World Bank data for 7 countries
  38. You: "Bitcoin price last 30 days" → CoinGecko live data
  39. ```
  40. No special syntax. No "use query_data". Just ask naturally — your agent handles the rest.
  41. <details>
  42. <summary><b>Manual install (if you prefer)</b></summary>
  43. **Claude Code:**
  44. ```bash
  45. claude mcp add --transport sse openecon-data https://data.openecon.ai/mcp --scope user
  46. ```
  47. **Codex:**
  48. ```bash
  49. codex mcp add openecon-data --url https://data.openecon.ai/mcp
  50. ```
  51. **Any MCP agent:** Endpoint `https://data.openecon.ai/mcp` (SSE transport)
  52. See [skills/README.md](skills/README.md) for slash commands and auto-trigger options.
  53. </details>
  54. ---
  55. <p align="center">
  56. <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" />
  57. </p>
  58. ## Why Your Agent Needs This
  59. 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:
  60. | | Without OpenEcon | With OpenEcon |
  61. |---|---|---|
  62. | **Data source** | LLM's training data (stale) | Official APIs (FRED, World Bank, IMF) |
  63. | **Accuracy** | Approximate, often wrong | Verified, with source attribution |
  64. | **Coverage** | Whatever the LLM remembers | 330K+ indicators, 200+ countries |
  65. | **Recency** | Months or years behind | Up to real-time (FRED, ExchangeRate) |
  66. | **Verifiable** | No source link | Every result includes source URL |
  67. ## How It Compares
  68. | Feature | OpenEcon | fredapi | pandas-datareader | fred-mcp-server |
  69. |---------|----------|---------|-------------------|-----------------|
  70. | Natural language queries | Yes | No | No | No |
  71. | Data sources | 10+ | 1 (FRED) | 7 | 1 (FRED) |
  72. | MCP server for AI agents | Yes | No | No | Yes |
  73. | Web UI with charts | Yes | No | No | No |
  74. | Conversational follow-ups | Yes | No | No | No |
  75. | Smart indicator discovery | 330K indexed | Keyword search | Keyword search | Keyword search |
  76. | Self-hostable | Yes | N/A | N/A | Yes |
  77. | No code required | Yes | No | No | No |
  78. ## What You Can Ask
  79. ```
  80. "US GDP growth last 10 years" → FRED, quarterly chart
  81. "Compare China, India, Brazil GDP 2018-2024" → World Bank, multi-country comparison
  82. "Inflation rate BRICS countries 2019-2023" → World Bank, 5 countries auto-expanded
  83. "EUR/USD exchange rate last 24 months" → ExchangeRate-API, currency pair chart
  84. "US unemployment and CPI together since 2010" → FRED, dual-axis overlay
  85. "China exports to the US 2020-2024" → UN Comtrade, bilateral trade flow
  86. "China manufacturing PMI this year" → ChinaMacro, fresh official NBS data
  87. "中国社会融资规模最近一年" → ChinaMacro, PBoC social financing
  88. "Credit to GDP ratio US, UK, Japan from BIS" → BIS, financial stability data
  89. "Bitcoin price last year" → CoinGecko, crypto chart
  90. "What inflation indicators does FRED have?" → Indicator discovery, text response
  91. ```
  92. **Conversational follow-ups work naturally:**
  93. ```
  94. You: "US GDP last 5 years" → chart with US GDP
  95. You: "add Germany and Japan" → updates to 3 countries
  96. You: "what about per capita?" → switches to GDP per capita
  97. You: "show only 2020-2023" → narrows time range
  98. ```
  99. ## Quick Start
  100. ### Use the web app (no setup)
  101. **[data.openecon.ai/chat](https://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.
  102. ### Self-host
  103. ```bash
  104. git clone https://github.com/hanlulong/openecon-data.git
  105. cd openecon-data
  106. ./scripts/setup.sh # Installs npm + Python deps, creates backend/.venv, copies .env.example → .env
  107. ```
  108. Then edit `.env` and set the two values the backend needs to start:
  109. ```bash
  110. OPENROUTER_API_KEY=sk-or-... # required (LLM parsing) — https://openrouter.ai/keys
  111. JWT_SECRET=... # required — generate with: openssl rand -hex 32
  112. ```
  113. Start both servers from the repo root, with the backend virtual environment activated (`npm run dev` runs `uvicorn` from your PATH):
  114. ```bash
  115. source backend/.venv/bin/activate
  116. npm run dev
  117. # Backend: http://localhost:3001 | Frontend: http://localhost:5173
  118. ```
  119. To restart, press Ctrl+C and run `npm run dev` again.
  120. Then ask your first question — plain English in, sourced data out:
  121. ```bash
  122. curl -X POST http://localhost:3001/api/query \
  123. -H "Content-Type: application/json" \
  124. -d '{"query": "US unemployment rate since 2023"}'
  125. ```
  126. ```jsonc
  127. {
  128. "data": [{
  129. "metadata": {
  130. "source": "FRED",
  131. "indicator": "Unemployment Rate",
  132. "unit": "Percent",
  133. "sourceUrl": "https://fred.stlouisfed.org/series/UNRATE" // every result links to its source
  134. },
  135. "data": [{ "date": "2023-01-01", "value": 3.4 }, /* ... */]
  136. }]
  137. }
  138. ```
  139. <details>
  140. <summary><b>Manual setup (if you prefer not to use setup.sh)</b></summary>
  141. ```bash
  142. npm install
  143. python3 -m venv backend/.venv
  144. source backend/.venv/bin/activate # Windows: backend\.venv\Scripts\activate
  145. pip install --upgrade pip
  146. pip install -r backend/requirements.txt
  147. cp .env.example .env # then set OPENROUTER_API_KEY and JWT_SECRET
  148. npm run dev # backend :3001, frontend :5173
  149. ```
  150. </details>
  151. <details>
  152. <summary><b>Requirements</b></summary>
  153. - Python 3.10+
  154. - Node.js 18+
  155. - **Required to start the backend:**
  156. - `OPENROUTER_API_KEY` — [OpenRouter API key](https://openrouter.ai/keys) for LLM parsing (required unless you set `LLM_PROVIDER` to a local model like `vllm`/`ollama`/`lm-studio`)
  157. - `JWT_SECRET` — any random secret; generate with `openssl rand -hex 32`
  158. - Optional: FRED API key, Comtrade API key, CoinGecko API key
  159. - Optional: Supabase credentials (enables real auth, Google sign-in, and persistent history; mock auth is used in development when omitted)
  160. See [Getting Started Guide](docs/guides/getting-started.md) for full setup instructions.
  161. </details>
  162. ### Use the HTTP API
  163. Prefer to call the service directly? The same natural-language queries work over HTTP. Base URL: `https://data.openecon.ai`.
  164. ```bash
  165. curl -X POST https://data.openecon.ai/api/query \
  166. -H "Content-Type: application/json" \
  167. -d '{"query": "US unemployment rate"}'
  168. ```
  169. There's also a streaming endpoint — `POST /api/query/stream` returns Server-Sent Events for real-time progress.
  170. See the [API Reference](docs/reference/api.md) for the full endpoint list and request/response schemas.
  171. ## How It Works
  172. ```
  173. "Compare US and ┌──────────────┐ ┌────────────────┐
  174. Japan inflation" ───▶ │ LLM Parser │ ───▶ │ LLM Router │
  175. │ (intent, │ │ (semantic │
  176. │ countries, │ │ routing + │
  177. │ dates) │ │ 330K index) │
  178. └──────────────┘ └───────┬────────┘
  179. │
  180. ┌────────────┐ ┌───────▼────────┐
  181. │ Chart + │ ◀────── │ Fetch from │
  182. │ CSV/JSON/ │ │ best provider │
  183. │ DTA/Python │ │ (FRED, WB, │
  184. └────────────┘ │ IMF, ...) │
  185. └────────────────┘
  186. ```
  187. 1. **Parse** — An LLM extracts intent, countries, indicators, and date range from plain English
  188. 2. **Route** — Semantic routing picks the best provider and series from 330K+ indicators
  189. 3. **Fetch** — Data retrieved from official APIs with automatic fallback if a source is down
  190. 4. **Return** — Interactive chart, or structured data via MCP for your agent
  191. ## Features
  192. **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.
  193. **Natural Language** — No API docs, no country codes, no series IDs. Just describe what you want.
  194. **Ask in Your Language** — Query in English, 中文, Español, Français, and more. The parser detects your language, finds the right indicator, and (for key messages) replies in kind. Try "北京的GDP" or "PIB de México".
  195. **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.
  196. **Multi-Round Conversations** — Follow up naturally: add countries, change time ranges, switch indicators. Context is preserved across turns, so "now add Germany" just works.
  197. **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.
  198. **Multi-Country Comparisons** — Say "G7", "BRICS", "EU", "ASEAN", "Nordic" or list specific countries. Auto-expands to all members.
  199. **Fast** — Repeat queries return in ~0.1 seconds. First-time queries typically take a few seconds; the first uncached query can take longer.
  200. **Resilient** — If one provider is down, the system automatically falls back to the next-best source. No manual retries needed.
  201. **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.
  202. **Multi-Format Export** — CSV, JSON, DTA (Stata), and Python code. Every export includes source attribution.
  203. **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.
  204. **Streaming** — Real-time progress via Server-Sent Events.
  205. **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).
  206. **Self-Hostable** — AGPL-3.0 licensed. Add new providers by implementing a single base class.
  207. ## Performance
  208. | Metric | Value |
  209. |--------|-------|
  210. | First query | typically a few seconds (first uncached query can take longer) |
  211. | Repeat query (cached) | ~0.1s |
  212. | Indicator database | 330,000+ indexed series across 11 providers |
  213. ## Data Sources
  214. 11 providers, 330K+ indexed indicators:
  215. | Provider | Coverage | Indicators | API Key |
  216. |----------|----------|-----------|---------|
  217. | **FRED** | US macroeconomic data (GDP, CPI, employment, rates) | 90,000+ series | Free |
  218. | **World Bank** | Global development (200+ countries, poverty, health) | 16,000+ indicators | None |
  219. | **IMF** | Balance of payments, exchange rates, fiscal data | Extensive | None |
  220. | **Eurostat** | EU member states (HICP, labor, trade) | Extensive | None |
  221. | **UN Comtrade** | Bilateral trade flows by HS commodity code | All HS codes | Free |
  222. | **BIS** | Credit-to-GDP, property prices, debt securities | Curated | None |
  223. | **Statistics Canada** | Canadian economic tables (labor, trade, prices) | 40,000+ tables | None |
  224. | **OECD** | OECD member country statistics | Extensive | None |
  225. | **ExchangeRate-API** | 160+ currency pairs, live and historical | Live & historical | Free |
  226. | **CoinGecko** | Cryptocurrency prices and market data | 10,000+ coins | Free |
  227. | **ChinaMacro** | Fresh Chinese headline macro (PMI, M2, social financing, CPI/PPI, 10Y yield) | 23 curated series | None |
  228. This product uses the FRED® API but is not endorsed or certified by the Federal Reserve Bank of St. Louis. See the [FRED® API Terms of Use](https://fred.stlouisfed.org/docs/api/terms_of_use.html).
  229. ## Who Is This For?
  230. | Role | How they use it |
  231. |------|----------------|
  232. | **AI Agent Builders** | Add economic data capabilities to any MCP-compatible agent — verified data, not hallucinations |
  233. | **Economists & Researchers** | Quick data pulls for papers without writing API code |
  234. | **Policy Analysts** | Cross-country comparisons (G7, BRICS, EU) with one query |
  235. | **Students** | Learn by exploring — ask questions, see data, export for assignments |
  236. | **Journalists** | Fact-check economic claims against official sources in seconds |
  237. ## Architecture
  238. ```
  239. ┌─────────────────┐ ┌──────────────────┐ ┌──────────────────────────┐
  240. │ User / Agent │────▶│ FastAPI Backend │────▶│ Data Providers │
  241. │ │ │ │ │ │
  242. │ "US inflation" │ │ LLM Parser │ │ FRED · World Bank · IMF │
  243. │ │◀────│ LLM Router │◀────│ Eurostat · BIS · ... │
  244. │ Chart + Data │ │ 330K Index │ │ │
  245. └─────────────────┘ └──────────────────┘ └──────────────────────────┘
  246. │ │
  247. React Frontend MCP Endpoint
  248. (Vite + Recharts) (SSE Transport)
  249. ```
  250. **Stack:** Python · FastAPI · React · TypeScript · Vite · Recharts · Redis · OpenRouter
  251. ## Contributing
  252. Contributions welcome! See the [Developer & Contributor Guide](docs/development/DEVELOPER_CONTRIBUTOR_GUIDE.md).
  253. - [Open issues](https://github.com/hanlulong/openecon-data/issues) — bug reports and feature requests
  254. - [Documentation](docs/README.md) — full docs index
  255. - [Security policy](.github/SECURITY.md) — responsible disclosure
  256. If you find this useful, a star helps others discover the project.
  257. ## License
  258. [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).
  259. The copyright line, the "or (at your option) any later version" grant and the note that commits before the license change were released under MIT are in [NOTICE](NOTICE).

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.