cfdude/mcp-fred

MCP-FRED

Model Context Protocol server for Federal Reserve Economic Data (FRED) API

A comprehensive MCP server providing access to all FRED API endpoints with intelligent large data handling, project-based storage, and async job processing for AI assistants like Claude.

Features

• 12 MCP Tools covering 50+ FRED API endpoints (categories, releases, series, sources, tags, maps)
• Conservative Token Estimation - Automatically saves large datasets to files to prevent context overflow
• Project-Based Storage - Organized file management for economic data
• Async Job Processing - Background processing for large datasets (>10K observations)
• Multiple Transports - STDIO (local) and Streamable HTTP (remote) support
• Smart Output Handling - Auto-detect when to return data vs. save to file
• Type Safety - Full Pydantic validation for all inputs and outputs

Quick Start

Three Installation Options

Option 1: PyPI Installation (Easiest)

Install directly from PyPI using pip or uv:

# Using pip
pip install mcp-fred

# Or using uv (faster)
uv pip install mcp-fred

Usage with Claude Desktop:

Add to your Claude Desktop configuration file:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "fred": {
      "command": "uv",
      "args": ["--directory", "/path/to/your/virtualenv", "run", "mcp-fred"],
      "env": {
        "FRED_API_KEY": "your_api_key_here",
        "FRED_STORAGE_DIR": "/Users/username/Documents/fred-data"
      }
    }
  }
}

Restart Claude Desktop, and the FRED tools will be available!

Option 2: Claude Desktop Extension

The no-setup option - includes bundled Python environment!

Requirements:

• Python 3.11+
• uv package manager (brew install uv)

Installation:

1. Download mcp-fred.mcpb from GitHub Releases
2. Double-click the file (or run open mcp-fred.mcpb)
3. Enter your FRED API key when prompted
4. Done! The extension is now available in Claude Desktop

See for detailed instructions and troubleshooting.

Option 3: Manual Installation from Source

Prerequisites:

• Python 3.11 or higher
• FRED API key (free from fred.stlouisfed.org)

Installation:

1. Clone the repository:

   git clone https://github.com/cfdude/mcp-fred.git
   cd mcp-fred
   

2. Create virtual environment:

   python3.11 -m venv venv
   source venv/bin/activate  # On Windows: venv\Scripts\activate
   

3. Install dependencies:

   pip install -r requirements.txt
   

4. Configure environment:

   cp .env.example .env
   # Edit .env and add your FRED_API_KEY
   

Usage with Claude Desktop:

Add to your Claude Desktop configuration file:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "fred": {
      "command": "python",
      "args": ["-m", "mcp_fred"],
      "env": {
        "FRED_API_KEY": "your_api_key_here",
        "FRED_STORAGE_DIR": "/Users/username/Documents/fred-data"
      }
    }
  }
}

Restart Claude Desktop, and the FRED tools will be available!

CLI Usage Example:

Use the MCP CLI (or compatible host) to manage FRED data projects and background jobs:

# Create a new project workspace with canonical subdirectories
mcp-cli call fred_project_create --operation create --project macro-demo

# List known projects with file counts and storage metadata
mcp-cli call fred_project_list --operation list --output screen

# Review background job progress or filter for completed runs
mcp-cli call fred_job_list --operation list --status completed --output screen

# Cancel a long-running job when you no longer need the export
mcp-cli call fred_job_cancel --operation cancel --job_id fred-job-123

# Check the final status for a specific job (useful after cancellations)
mcp-cli call fred_job_status --operation get --job_id fred-job-123

Note: The CLI examples assume mcp-cli is configured with your FRED_API_KEY and optional FRED_STORAGE_DIR. Substitute actual job identifiers when invoking job status tools.

Available Tools

Data Retrieval Tools

Job Management Tools

Project Management Tools

How It Works

Smart Output Handling

MCP-FRED intelligently decides whether to return data directly or save to a file:

1. Small datasets (<50K tokens): Returned directly to Claude
2. Large datasets (>50K tokens): Saved to file automatically
3. Very large datasets (>10K observations): Processed in background job

Token Estimation

Conservative approach assuming 75% of context already used:

• Claude Sonnet: 50K safe limit (out of 200K total)
• GPT-4: 25K safe limit (out of 100K total)
• Gemini Pro: 250K safe limit (out of 1M total)

Project-Based Storage

Files are organized by project:

fred-data/
  my-project/
    series/          # Series observation data
    maps/            # GeoFRED shape files
    releases/        # Release data
    categories/      # Category data
    sources/         # Source data
    tags/            # Tag data
    .project.json    # Project metadata

Example Usage

In Claude Desktop, ask:

"Using FRED data, get GDP observations for the last 10 years and save it to the 'economy-2024' project"

Claude will:

1. Call fred_series with operation="get_observations"
2. Estimate dataset size (~40 observations)
3. Save to fred-data/economy-2024/series/GNPCA_observations.csv
4. Return file path for further analysis

For large datasets:

"Get all unemployment observations since 1948"

Claude will:

1. Estimate size (>10K observations)
2. Create background job
3. Return job ID immediately
4. Check status with fred_job_status
5. Get file path when complete

Configuration

All configuration via environment variables (.env file or MCP client config):

Required

• FRED_API_KEY - Your FRED API key

Optional

• FRED_STORAGE_DIR - Storage location (default: ./fred-data)
• FRED_PROJECT_NAME - Default project name (default: default)
• FRED_OUTPUT_FORMAT - Default format: csv or json (default: csv)
• FRED_OUTPUT_MODE - Output mode: auto, screen, or file (default: auto)
• FRED_OUTPUT_FILE_CHUNK_SIZE - Rows per CSV flush (default: 1000)
• FRED_JOB_RETENTION_HOURS - Job retention period (default: 24)

See .env.example for complete list.

Development

Setup Development Environment

# Clone and setup
git clone https://github.com/cfdude/mcp-fred.git
cd mcp-fred
git checkout dev

# Create virtual environment
python3.11 -m venv venv
source venv/bin/activate

# Install dependencies
pip install -r requirements.txt

# Configure environment
cp .env.example .env
# Edit .env with your FRED_API_KEY

Run Tests

# Run all tests with coverage
pytest --cov=mcp_fred --cov-report=html

# Run specific tests
pytest tests/test_tools/test_series.py

# Run with verbose output
pytest -v

Code Quality

# Lint and format
ruff check .
ruff format .

# Fix auto-fixable issues
ruff check --fix .

Documentation

• - Quick start for new AI contexts
• - System architecture and design
• - Complete FRED API to Tool mapping
• - Series & maps tool usage
• - Developer setup guide
• - Why each dependency was chosen
• - Development task list (8 phases)
• - CI/CD workflows and pre-commit hooks

CI/CD

Automated testing and security checks run on every commit and pull request.

Install pre-commit hook (recommended for development):

./scripts/install-pre-commit-hook.sh

The hook runs before each commit:

• Code formatting check (ruff)
• Linting (ruff)
• Full test suite (pytest)
• Coverage validation (80% minimum)

GitHub Actions workflows:

• CI: Tests, formatting, linting on Python 3.11 & 3.12
• Security: Secret scanning, dependency vulnerabilities

See for complete details.

Architecture

Core Components

mcp-fred/
  src/mcp_fred/
    server.py           # MCP server entry point
    config.py           # Configuration management
    api/                # FRED API client
      client.py         # Async HTTP client
      endpoints/        # API endpoint implementations
      models/           # Pydantic response models
    tools/              # MCP tool implementations (12 tools)
    utils/              # Utilities
      token_estimator.py    # Token counting (tiktoken)
      file_handler.py       # File I/O and path security
      json_to_csv.py        # JSON to CSV conversion
      job_manager.py        # Async job tracking
      background_worker.py  # Background task processing
    transports/         # STDIO and HTTP transports
  tests/                # Test suite (80% coverage target)

Key Design Decisions

1. Conservative Token Limits: Assume 75% context used, safe limits at 25% of total
2. Project-Based Storage: User-configurable directory, organized subdirectories
3. Async Job Processing: Background jobs for datasets >10K rows or >10 seconds
4. Type Safety: Pydantic for all validation, runtime error catching
5. Error Handling: Consistent JSON error responses with codes and details

FRED API Coverage

50+ FRED API endpoints mapped to 12 MCP tools

Critical Operations (Large Data)

• Series Observations: Up to 100K observations per series
• GeoFRED Maps: Shape files can be 1MB+ per region

Rate Limits

• 120 requests per minute (FRED API limit)
• Automatic retry with exponential backoff

Testing Philosophy

• Target: 80% code coverage minimum
• Focus: Unit tests (primary), integration tests (as needed)
• Mocking: Mock FRED API responses, no real API calls in tests
• No E2E: MCP product doesn't require end-to-end testing
• Reference: See for scenarios, fixtures, and tooling details.

Contributing

We welcome contributions! Please:

1. Fork the repository
2. Create a feature branch (git checkout -b feature/amazing-feature)
3. Follow conventional commit format (feat:, fix:, docs:, etc.)
4. Run tests and linting (pytest && ruff check .)
5. Submit a pull request to dev branch

License

This project is licensed under the MIT License - see the file for details.

Acknowledgments

• FRED API: Federal Reserve Bank of St. Louis for providing free economic data API
• Model Context Protocol: Anthropic for the MCP specification
• Snowflake MCP: Inspiration for smart output handling approach

Support

• Issues: GitHub Issues
• FRED API Docs: fred.stlouisfed.org/docs/api
• MCP Specification: modelcontextprotocol.io