FRED Agentic Economic Intelligence MCP

An open-source, MCP-native economic intelligence server built on the Federal Reserve Economic Data API. The project combines deterministic FRED tools with a curated economic knowledge graph, graph-enhanced retrieval, explainability, an Economic Digital Twin, scenario simulation, and a LangGraph-compatible multi-agent workflow.

Capabilities

• FRED series search, metadata, observations, comparison, snapshots, and calendar-aware growth calculations
• MCP tools for economic graph queries and evidence retrieval
• Curated macroeconomic knowledge graph with transparent edges and confidence metadata
• Lightweight GraphRAG using graph traversal plus local evidence retrieval
• Economic Digital Twin with growth, inflation, labor, policy, housing, and financial-condition states
• Directional scenario simulation with propagation traces and explicit limitations
• Explainability through data provenance, domain attribution, graph paths, and citations
• Supervisor-led multi-agent workflow compatible with LangGraph
• Deterministic fallback mode that does not require an LLM API key

Important scope statement

This is a research-grade decision-support project. The digital twin and scenario engine are transparent directional models, not validated causal macroeconomic forecasts or investment advice.

Install

uv sync

Create a .env file locally:

FRED_API_KEY=your_fred_api_key

Never commit the .env file.

Run

uv run python -m fred_economic_intelligence_mcp.server

Or:

uv run fred-economic-intelligence-mcp

Main MCP tools

FRED data

• health_check
• search_series
• get_series_metadata
• get_series_observations
• compare_series
• latest_snapshot
• calculate_growth_rate

Agentic intelligence

• query_economic_graph
• retrieve_economic_evidence
• build_economic_digital_twin
• simulate_economic_scenario
• explain_economic_signal
• run_agent_workflow

Normalized signal convention

Digital-twin inputs use values from -1.0 to 1.0:

• positive: indicator increased or strengthened
• negative: indicator decreased or weakened
• zero: neutral or unavailable

The twin applies indicator-specific interpretation. For example, increases in unemployment or initial claims contribute negatively to labor-market strength.

Example:

{
  "CPIAUCSL": 0.25,
  "UNRATE": 0.40,
  "PAYEMS": -0.10,
  "HOUST": -0.30,
  "T10Y2Y": -0.50
}

Scenario shocks

Supported MVP shocks:

• policy_rate_change
• unemployment_change
• inflation_change

Example:

{
  "policy_rate_change": -0.5
}

Test

uv run pytest -v --cov=fred_economic_intelligence_mcp --cov-report=term-missing

Open-source release

Before publishing, ensure .env, .venv, .coverage, caches, and Git internals are excluded from the archive and repository.

<!-- mcp-name: io.github.prithvi1029/fred-economic-intelligence -->