# 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

```powershell
uv sync
```

Create a `.env` file locally:

```text
FRED_API_KEY=your_fred_api_key
```

Never commit the `.env` file.

## Run

```powershell
uv run python -m fred_economic_intelligence_mcp.server
```

Or:

```powershell
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:

```json
{
  "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:

```json
{
  "policy_rate_change": -0.5
}
```

## Test

```powershell
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 -->