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

• Built on FastMCP 3.0.0b1 - Modern decorator-based MCP framework with context injection

• 39 MCP Tools covering 50+ FRED API endpoints (categories, releases, series, sources, tags, maps)

• Progressive Disclosure - 29 core tools visible by default, 16 additional tools activated on-demand

• Per-Session Activation - Enable data, advanced, or admin tool tiers as needed

• 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)

• Smart Output Handling - Auto-detect when to return data vs. save to file

• Type Safety - Full Pydantic validation for all inputs and outputs

Related MCP server: fred-mcp-server

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 EXTENSION.md 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

MCP-FRED uses progressive disclosure to reduce context overhead. Core and discovery tools are always visible; additional tiers can be activated per-session.

Tool Tiers

Use activate_all_tools() to enable all tiers at once, or list_tool_tiers() to see available tools.

Core Tools (Always Available)

Discovery Tools (Always Available)

Data Tools (Activate with activate_data_tools())

Admin Tools (Activate with activate_admin_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

• CONTEXT.md - Quick start for new AI contexts

• ARCHITECTURE.md - System architecture and design

• API_MAPPING.md - Complete FRED API to Tool mapping

• SERIES_MAPS_GUIDE.md - Series & maps tool usage

• DEVELOPMENT_GUIDE.md - Developer setup guide

• DEPENDENCIES.md - Why each dependency was chosen

• TODO.md - Development task list (8 phases)

• CI_CD.md - 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 CI_CD.md for complete details.

Architecture

Built on FastMCP 3.0.0b1

MCP-FRED is built on FastMCP 3.0.0b1, the modern Python framework for building MCP servers. Key framework features used:

• Decorator-based tool registration - @mcp.tool() decorators for clean tool definitions

• Context injection - CurrentContext() dependency provides access to shared resources

• Lifespan management - @lifespan decorator handles initialization and cleanup

• Tag-based visibility - mcp.disable(tags={...}) and ctx.enable_components() for progressive disclosure

• Tool annotations - readOnlyHint, idempotentHint for LLM optimization

Core Components

mcp-fred/
  src/mcp_fred/
    fastmcp_server.py   # FastMCP entry point with progressive disclosure
    config.py           # Configuration management
    servers/            # FastMCP tool modules (39 tools)
      base.py           # Server instance and lifespan context
      admin.py          # Job/project management + activation tools
      categories.py     # Category tools
      releases.py       # Release tools
      series.py         # Series tools (largest module)
      sources.py        # Source tools
      tags.py           # Tag tools
      maps.py           # GeoFRED tools
      common.py         # Shared utilities (smart_output, error formatting)
    api/                # FRED API client
      client.py         # Async HTTP client with retry/backoff
      endpoints/        # API endpoint implementations
      models/           # Pydantic response models
    utils/              # Utilities
      token_estimator.py    # Token counting (tiktoken)
      output_handler.py     # Smart output routing
      json_to_csv.py        # JSON to CSV conversion
      job_manager.py        # Async job tracking
      background_worker.py  # Background task processing
    tools/              # Legacy tool implementations (for MCPFRED_LEGACY=1)
    transports/         # Legacy STDIO transport
  tests/                # Test suite (80% coverage target)

Key Design Decisions

1. FastMCP 3.0.0b1 - Modern framework with decorator-based tools and context injection

2. Progressive Disclosure - 29 tools visible by default, 16 activated on-demand to reduce LLM context overhead

3. Conservative Token Limits - Assume 75% context used, safe limits at 25% of total

4. Project-Based Storage - User-configurable directory, organized subdirectories

5. Async Job Processing - Background jobs for datasets >10K rows or >10 seconds

6. Type Safety - Pydantic for all validation, runtime error catching

7. Legacy Support - Set MCPFRED_LEGACY=1 to use old STDIO transport

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 docs/TESTING_STRATEGY.md 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 LICENSE 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