Installation Guide

This guide covers all installation methods for the FRED MCP Server across different platforms and deployment scenarios.

Prerequisites

FRED API Key

Required for accessing FRED data. Get your free key at fred.stlouisfed.org

Node.js 18+

Required for running the server. Download from nodejs.org

Installation Methods

Method 1: Automatic Installation (Recommended)

Smithery CLI
NPM Global
NPM Local

The easiest installation method using Smithery:

npx -y @smithery/cli install @stefanoamorelli/fred-mcp-server --client claude

Benefits:

Automatic configuration
Handles all dependencies
Interactive setup for API key
Updates configuration automatically

Install globally for system-wide access:

# Install globally
npm install -g fred-mcp-server

# Verify installation
fred-mcp-server --version

Benefits:

Available system-wide
Easy updates via npm
Simple command-line usage

Install in a specific project:

# Create project directory
mkdir my-fred-project
cd my-fred-project

# Initialize and install
npm init -y
npm install fred-mcp-server

# Run with npx
npx fred-mcp-server

Benefits:

Project-specific installation
Version control friendly
No global dependencies

Method 2: From Source

Clone Repository

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

Install Dependencies

# Using pnpm (recommended)
pnpm install

# Or using npm
npm install

# Or using yarn
yarn install

Build the Project

# Build TypeScript
pnpm build

# Or with npm
npm run build

Verify Build

# Test the build
node build/index.js --version

Method 3: Docker

Pre-built Image
Build Custom Image

Use the official Docker image:

# Pull the latest image
docker pull stefanoamorelli/fred-mcp-server:latest

# Run the container
docker run -i --rm \
  -e FRED_API_KEY=your_api_key_here \
  stefanoamorelli/fred-mcp-server:latest

Build your own Docker image:

# Dockerfile
FROM node:18-alpine

WORKDIR /app

# Copy package files
COPY package*.json ./
RUN npm ci --only=production

# Copy application
COPY . .
RUN npm run build

# Set entrypoint
ENTRYPOINT ["node", "build/index.js"]

Build and run:

docker build -t my-fred-mcp .
docker run -i --rm -e FRED_API_KEY=key my-fred-mcp

Client Configuration

Claude Desktop

Configuration file locations

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
Windows: %APPDATA%\Claude\claude_desktop_config.json
Linux: ~/.config/claude/claude_desktop_config.json

Standard Setup
Local Build
Docker

{
  "mcpServers": {
    "fred-mcp": {
      "command": "fred-mcp-server",
      "env": {
        "FRED_API_KEY": "your_api_key_here"
      }
    }
  }
}

{
  "mcpServers": {
    "fred-mcp": {
      "command": "node",
      "args": ["/path/to/fred-mcp-server/build/index.js"],
      "env": {
        "FRED_API_KEY": "your_api_key_here"
      }
    }
  }
}

{
  "mcpServers": {
    "fred-mcp": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "-e",
        "FRED_API_KEY=your_api_key_here",
        "stefanoamorelli/fred-mcp-server:latest"
      ]
    }
  }
}

Other MCP Clients

VSCode Extension

Configure in .vscode/settings.json:

{
  "mcp.servers": {
    "fred": {
      "command": "fred-mcp-server",
      "env": {
        "FRED_API_KEY": "${env:FRED_API_KEY}"
      }
    }
  }
}

Command Line Client

Use with any MCP CLI client:

# Set environment variable
export FRED_API_KEY="your_api_key"

# Run with MCP CLI
mcp-cli connect fred-mcp-server

Python Client

Use with Python MCP client:

from mcp import Client
import os

# Configure client
client = Client()
client.connect(
    command="fred-mcp-server",
    env={"FRED_API_KEY": os.getenv("FRED_API_KEY")}
)

# Use the client
result = client.call_tool(
    "fred_get_series",
    {"series_id": "GDP", "limit": 10}
)

Environment Variables

FRED_API_KEY

string

required

Your FRED API key from fred.stlouisfed.org

FRED_BASE_URL

string

default:"https://api.stlouisfed.org/fred"

Optional: Override the FRED API base URL

LOG_LEVEL

string

default:"info"

Optional: Set logging level (debug, info, warn, error)

Platform-Specific Instructions

macOS

Install Prerequisites

# Install Homebrew if needed
/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

# Install Node.js
brew install node

Install FRED MCP

npm install -g fred-mcp-server

Configure Claude

# Open config in editor
code ~/Library/Application\ Support/Claude/claude_desktop_config.json

Windows

Install Prerequisites

Download Node.js from nodejs.org
Run the installer with default settings
Open PowerShell or Command Prompt as Administrator

Install FRED MCP

npm install -g fred-mcp-server

Configure Claude

# Open config directory
explorer %APPDATA%\Claude

# Edit claude_desktop_config.json

Linux

Install Prerequisites

# Ubuntu/Debian
sudo apt update
sudo apt install nodejs npm

# Fedora
sudo dnf install nodejs npm

# Arch
sudo pacman -S nodejs npm

Install FRED MCP

sudo npm install -g fred-mcp-server

Configure Claude

# Create config directory if needed
mkdir -p ~/.config/claude

# Edit configuration
nano ~/.config/claude/claude_desktop_config.json

Verification

Test Installation

# Test the server directly
FRED_API_KEY=your_key fred-mcp-server

# Should output MCP initialization message

# Test Docker installation
docker run -i --rm \
  -e FRED_API_KEY=your_key \
  stefanoamorelli/fred-mcp-server:latest \
  <<< '{"jsonrpc":"2.0","method":"tools/list","id":1}'

// test.js
const { spawn } = require('child_process');

const server = spawn('fred-mcp-server', [], {
  env: { ...process.env, FRED_API_KEY: 'your_key' }
});

server.stdout.on('data', (data) => {
  console.log(`Server: ${data}`);
});

Troubleshooting

Command not found

Issue: fred-mcp-server: command not foundSolutions:

Ensure Node.js is installed: node --version
Check npm global bin path: npm bin -g
Add npm bin to PATH: export PATH=$PATH:$(npm bin -g)
Reinstall: npm install -g fred-mcp-server

Permission denied

Issue: Permission errors during installationSolutions:

macOS/Linux: Use sudo npm install -g fred-mcp-server
Windows: Run as Administrator
Alternative: Install locally without -g flag

API Key errors

Issue: “Invalid API key” or authentication errorsSolutions:

Verify key at fred.stlouisfed.org
Check for typos in configuration
Ensure proper JSON formatting
Test key with curl:

curl "https://api.stlouisfed.org/fred/series?series_id=GDP&api_key=YOUR_KEY&file_type=json"

Docker issues

Issue: Docker container exits immediatelySolutions:

Run with -it flags for interactive mode
Check Docker logs: docker logs container_id
Verify environment variables are passed correctly
Ensure Docker daemon is running

Updating

Update Methods

NPM Update
Git Update
Docker Update

# Update globally installed version
npm update -g fred-mcp-server

# Or reinstall latest
npm install -g fred-mcp-server@latest

# In your cloned repository
git pull origin main
pnpm install
pnpm build

# Pull latest image
docker pull stefanoamorelli/fred-mcp-server:latest

# Remove old image (optional)
docker image prune

Next Steps

Configuration

Advanced configuration options

API Reference

Explore available tools

Examples

Start using FRED data

Troubleshooting

Common issues and solutions

​Installation Guide

​Prerequisites

FRED API Key

Node.js 18+

​Installation Methods

​Method 1: Automatic Installation (Recommended)

​Method 2: From Source

​Method 3: Docker

​Client Configuration

​Claude Desktop

​Other MCP Clients

​Environment Variables

​Platform-Specific Instructions

​macOS

​Windows

​Linux

​Verification

​Test Installation

​Troubleshooting

​Updating

​Update Methods

​Next Steps

Configuration

API Reference

Examples

Troubleshooting

Installation Guide

Prerequisites

Installation Methods

Method 1: Automatic Installation (Recommended)

Method 2: From Source

Method 3: Docker

Client Configuration

Claude Desktop

Other MCP Clients

Environment Variables

Platform-Specific Instructions

macOS

Windows

Linux

Verification

Test Installation

Troubleshooting

Updating

Update Methods

Next Steps