> ## Documentation Index
> Fetch the complete documentation index at: https://fred-mcp-server.amorelli.tech/llms.txt
> Use this file to discover all available pages before exploring further.

# Installation

> Comprehensive installation guide for all platforms and methods

# Installation Guide

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

## Prerequisites

<CardGroup cols={2}>
  <Card title="FRED API Key" icon="key">
    Required for accessing FRED data. Get your free key at [fred.stlouisfed.org](https://fred.stlouisfed.org/docs/api/api_key.html)
  </Card>

  <Card title="Node.js 18+" icon="node">
    Required for running the server. Download from [nodejs.org](https://nodejs.org)
  </Card>
</CardGroup>

## Installation Methods

### Method 1: Automatic Installation (Recommended)

<Tabs>
  <Tab title="Smithery CLI">
    The easiest installation method using [Smithery](https://smithery.ai):

    ```bash theme={null}
    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
  </Tab>

  <Tab title="NPM Global">
    Install globally for system-wide access:

    ```bash theme={null}
    # 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
  </Tab>

  <Tab title="NPM Local">
    Install in a specific project:

    ```bash theme={null}
    # 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
  </Tab>
</Tabs>

### Method 2: From Source

<Steps>
  <Step title="Clone Repository">
    ```bash theme={null}
    git clone https://github.com/stefanoamorelli/fred-mcp-server.git
    cd fred-mcp-server
    ```
  </Step>

  <Step title="Install Dependencies">
    ```bash theme={null}
    # Using pnpm (recommended)
    pnpm install

    # Or using npm
    npm install

    # Or using yarn
    yarn install
    ```
  </Step>

  <Step title="Build the Project">
    ```bash theme={null}
    # Build TypeScript
    pnpm build

    # Or with npm
    npm run build
    ```
  </Step>

  <Step title="Verify Build">
    ```bash theme={null}
    # Test the build
    node build/index.js --version
    ```
  </Step>
</Steps>

### Method 3: Docker

<Tabs>
  <Tab title="Pre-built Image">
    Use the official Docker image:

    ```bash theme={null}
    # 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
    ```
  </Tab>

  <Tab title="Build Custom Image">
    Build your own Docker image:

    ```dockerfile theme={null}
    # 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:

    ```bash theme={null}
    docker build -t my-fred-mcp .
    docker run -i --rm -e FRED_API_KEY=key my-fred-mcp
    ```
  </Tab>
</Tabs>

## Client Configuration

### Claude Desktop

<Accordion title="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`
</Accordion>

<Tabs>
  <Tab title="Standard Setup">
    ```json theme={null}
    {
      "mcpServers": {
        "fred-mcp": {
          "command": "fred-mcp-server",
          "env": {
            "FRED_API_KEY": "your_api_key_here"
          }
        }
      }
    }
    ```
  </Tab>

  <Tab title="Local Build">
    ```json theme={null}
    {
      "mcpServers": {
        "fred-mcp": {
          "command": "node",
          "args": ["/path/to/fred-mcp-server/build/index.js"],
          "env": {
            "FRED_API_KEY": "your_api_key_here"
          }
        }
      }
    }
    ```
  </Tab>

  <Tab title="Docker">
    ```json theme={null}
    {
      "mcpServers": {
        "fred-mcp": {
          "command": "docker",
          "args": [
            "run",
            "-i",
            "--rm",
            "-e",
            "FRED_API_KEY=your_api_key_here",
            "stefanoamorelli/fred-mcp-server:latest"
          ]
        }
      }
    }
    ```
  </Tab>
</Tabs>

### Other MCP Clients

<AccordionGroup>
  <Accordion title="VSCode Extension">
    Configure in `.vscode/settings.json`:

    ```json theme={null}
    {
      "mcp.servers": {
        "fred": {
          "command": "fred-mcp-server",
          "env": {
            "FRED_API_KEY": "${env:FRED_API_KEY}"
          }
        }
      }
    }
    ```
  </Accordion>

  <Accordion title="Command Line Client">
    Use with any MCP CLI client:

    ```bash theme={null}
    # Set environment variable
    export FRED_API_KEY="your_api_key"

    # Run with MCP CLI
    mcp-cli connect fred-mcp-server
    ```
  </Accordion>

  <Accordion title="Python Client">
    Use with Python MCP client:

    ```python theme={null}
    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}
    )
    ```
  </Accordion>
</AccordionGroup>

## Environment Variables

<ParamField path="FRED_API_KEY" type="string" required>
  Your FRED API key from fred.stlouisfed.org
</ParamField>

<ParamField path="FRED_BASE_URL" type="string" default="https://api.stlouisfed.org/fred">
  Optional: Override the FRED API base URL
</ParamField>

<ParamField path="LOG_LEVEL" type="string" default="info">
  Optional: Set logging level (debug, info, warn, error)
</ParamField>

## Platform-Specific Instructions

### macOS

<Steps>
  <Step title="Install Prerequisites">
    ```bash theme={null}
    # Install Homebrew if needed
    /bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

    # Install Node.js
    brew install node
    ```
  </Step>

  <Step title="Install FRED MCP">
    ```bash theme={null}
    npm install -g fred-mcp-server
    ```
  </Step>

  <Step title="Configure Claude">
    ```bash theme={null}
    # Open config in editor
    code ~/Library/Application\ Support/Claude/claude_desktop_config.json
    ```
  </Step>
</Steps>

### Windows

<Steps>
  <Step title="Install Prerequisites">
    1. Download Node.js from [nodejs.org](https://nodejs.org)
    2. Run the installer with default settings
    3. Open PowerShell or Command Prompt as Administrator
  </Step>

  <Step title="Install FRED MCP">
    ```powershell theme={null}
    npm install -g fred-mcp-server
    ```
  </Step>

  <Step title="Configure Claude">
    ```powershell theme={null}
    # Open config directory
    explorer %APPDATA%\Claude

    # Edit claude_desktop_config.json
    ```
  </Step>
</Steps>

### Linux

<Steps>
  <Step title="Install Prerequisites">
    ```bash theme={null}
    # Ubuntu/Debian
    sudo apt update
    sudo apt install nodejs npm

    # Fedora
    sudo dnf install nodejs npm

    # Arch
    sudo pacman -S nodejs npm
    ```
  </Step>

  <Step title="Install FRED MCP">
    ```bash theme={null}
    sudo npm install -g fred-mcp-server
    ```
  </Step>

  <Step title="Configure Claude">
    ```bash theme={null}
    # Create config directory if needed
    mkdir -p ~/.config/claude

    # Edit configuration
    nano ~/.config/claude/claude_desktop_config.json
    ```
  </Step>
</Steps>

## Verification

### Test Installation

<CodeGroup>
  ```bash Command Line theme={null}
  # Test the server directly
  FRED_API_KEY=your_key fred-mcp-server

  # Should output MCP initialization message
  ```

  ```bash Docker Test theme={null}
  # 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}'
  ```

  ```javascript Node.js Test theme={null}
  // 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}`);
  });
  ```
</CodeGroup>

### Troubleshooting

<AccordionGroup>
  <Accordion title="Command not found">
    **Issue**: `fred-mcp-server: command not found`

    **Solutions**:

    1. Ensure Node.js is installed: `node --version`
    2. Check npm global bin path: `npm bin -g`
    3. Add npm bin to PATH: `export PATH=$PATH:$(npm bin -g)`
    4. Reinstall: `npm install -g fred-mcp-server`
  </Accordion>

  <Accordion title="Permission denied">
    **Issue**: Permission errors during installation

    **Solutions**:

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

  <Accordion title="API Key errors">
    **Issue**: "Invalid API key" or authentication errors

    **Solutions**:

    1. Verify key at [fred.stlouisfed.org](https://fred.stlouisfed.org)
    2. Check for typos in configuration
    3. Ensure proper JSON formatting
    4. Test key with curl:

    ```bash theme={null}
    curl "https://api.stlouisfed.org/fred/series?series_id=GDP&api_key=YOUR_KEY&file_type=json"
    ```
  </Accordion>

  <Accordion title="Docker issues">
    **Issue**: Docker container exits immediately

    **Solutions**:

    1. Run with `-it` flags for interactive mode
    2. Check Docker logs: `docker logs container_id`
    3. Verify environment variables are passed correctly
    4. Ensure Docker daemon is running
  </Accordion>
</AccordionGroup>

## Updating

### Update Methods

<Tabs>
  <Tab title="NPM Update">
    ```bash theme={null}
    # Update globally installed version
    npm update -g fred-mcp-server

    # Or reinstall latest
    npm install -g fred-mcp-server@latest
    ```
  </Tab>

  <Tab title="Git Update">
    ```bash theme={null}
    # In your cloned repository
    git pull origin main
    pnpm install
    pnpm build
    ```
  </Tab>

  <Tab title="Docker Update">
    ```bash theme={null}
    # Pull latest image
    docker pull stefanoamorelli/fred-mcp-server:latest

    # Remove old image (optional)
    docker image prune
    ```
  </Tab>
</Tabs>

## Next Steps

<CardGroup cols={2}>
  <Card title="Configuration" icon="gear" href="/configuration">
    Advanced configuration options
  </Card>

  <Card title="API Reference" icon="code" href="/api-reference/overview">
    Explore available tools
  </Card>

  <Card title="Examples" icon="flask" href="/examples/basic-usage">
    Start using FRED data
  </Card>

  <Card title="Troubleshooting" icon="wrench" href="/resources/troubleshooting">
    Common issues and solutions
  </Card>
</CardGroup>