Skip to main content

​
Authentication

Access to the FRED API requires a free API key. This guide covers how to obtain and configure your API key securely.

​
Getting an API Key

​
Registration Process

1

Create Account

Visit FRED API Registration and create a free account
2

Request API Key

Click “Request API Key” and fill out the brief application form
3

Instant Approval

Your API key will be generated immediately and displayed on screen
4

Save Securely

Store your key securely - you’ll need it for configuration
API keys are completely free with no usage fees. Rate limits apply but are generous for most use cases.

​
API Key Format

Keys are 32-character alphanumeric strings: 
a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6

​
Configuration

The most secure method is using environment variables.
Edit ~/Library/Application Support/Claude/claude_desktop_config.json:
{
  "mcpServers": {
    "fred": {
      "command": "npx",
      "args": ["-y", "fred-mcp-server"],
      "env": {
        "FRED_API_KEY": "your-api-key-here"
      }
    }
  }
}

​
Verification

Test your configuration: 
# Using the MCP server directly
FRED_API_KEY=your-key npx fred-mcp-server

# Or if set in environment
npx fred-mcp-server
The server should start without errors. If you see authentication errors, verify your key is correct.

​
Security Best Practices

​
Key Protection

❌ Don’t:
// config.json
{
  "api_key": "a1b2c3d4e5f6g7h8..."
}
✅ Do:
// config.json (use environment variables)
{
  "api_key": "${FRED_API_KEY}"
}
Limit who can read configuration files:
chmod 600 ~/.claude/config.json
chmod 600 .env
Create different keys for:
  • Development environments
  • Production systems
  • Different applications
This allows selective revocation if needed.
Periodically generate new keys and update your configuration

​
Access Control

The FRED MCP Server never:
  • Logs API keys
  • Exposes keys in responses
  • Stores keys persistently
  • Transmits keys except to FRED API
Keys are only used for authenticated requests to api.stlouisfed.org.

​
Rate Limits

FRED API implements rate limiting to ensure fair usage.

​
Current Limits

Limit TypeRestrictionNotes
Requests per Minute120Across all endpoints
Series Observations40/minSpecific to data retrieval
Daily RequestsVariesBased on account tier

​
Handling Rate Limits

The MCP server implements automatic handling: 
{
  maxRetries: 3,
  backoffMultiplier: 2,
  initialDelay: 1000 // ms
}

​
Best Practices

1

Batch Requests

Group related queries to minimize API calls
2

Use Date Ranges

Request only the time periods you need
3

Avoid Unnecessary Requests

Plan queries carefully to minimize redundant API calls
4

Off-Peak Usage

Schedule heavy queries during off-peak hours

​
Troubleshooting

​
Common Issues

Symptoms: “Bad Request. The value for variable api_key is not registered.”Solutions:
  • Verify API key is correct (check for typos)
  • Ensure environment variable is set
  • Restart the MCP server after changing config
  • Check key hasn’t been revoked
Symptoms: “Too many requests”Solutions:
  • Wait 60 seconds before retrying
  • Reduce request frequency
  • Use date ranges to limit data size
  • Use fewer concurrent requests
Symptoms: Server starts but requests failSolutions:
  • Check variable name is exactly FRED_API_KEY
  • Verify it’s set in the correct profile file
  • Restart terminal/application after setting
  • Use absolute paths in configuration
Symptoms: JSON parsing errorsSolutions:
  • Verify API key format (32 hex characters)
  • Check for special characters in key
  • Ensure no whitespace in environment variable

​
Debug Mode

Enable detailed logging: 
DEBUG=fred:* npx fred-mcp-server
This shows:
  • Request URLs (with key redacted)
  • Response status codes
  • Rate limit status
  • Error details

​
Key Management

​
Regenerating Keys

If your key is compromised:
1

Login to FRED Account

Visit your API Keys page
2

Revoke Old Key

Click “Delete” next to the compromised key
3

Generate New Key

Click “Request API Key” to create a replacement
4

Update Configuration

Replace the old key in all your configurations
5

Restart Services

Restart MCP server and any dependent applications

​
Multiple Keys

You can have multiple API keys: 
{
  "mcpServers": {
    "fred-dev": {
      "command": "npx",
      "args": ["-y", "fred-mcp-server"],
      "env": {
        "FRED_API_KEY": "development-key"
      }
    },
    "fred-prod": {
      "command": "npx",
      "args": ["-y", "fred-mcp-server"],
      "env": {
        "FRED_API_KEY": "production-key"
      }
    }
  }
}

​
Terms of Use

By using the FRED API, you agree to:

Attribution

Credit Federal Reserve Bank of St. Louis and FRED

Non-Commercial

Free for research, education, and personal use

No Resale

Don’t redistribute raw data commercially

Respect Limits

Adhere to rate limits and usage guidelines
For commercial use or higher limits, contact the FRED team directly.

​
Next Steps

Quickstart

Start using the MCP server

API Reference

Explore available tools

Examples

See usage examples

Troubleshooting

Get help with issues