Faim Time Series Forecasting

FAIM MCP Server

A Model Context Protocol (MCP) server that integrates the FAIM time series forecasting SDK with any MCP-compatible AI assistant, enabling AI-powered forecasting capabilities.

NPM Package: @faim-group/mcp

Overview

This MCP server currently exposes two foundation time-series models from the FAIM API for zero-shot forecasting:

• Chronos2
• TiRex

Key Features

✅ Two MCP Tools:

• list_models: Returns available forecasting models and capabilities
• forecast: Performs point and probabilistic time series forecasting

✅ Flexible Input Formats:

• 1D arrays: Single univariate time series
• 3D arrays: batch/sequence/feature format

✅ Probabilistic Forecasting:

• Point forecasts (single value predictions)
• Quantile forecasts (confidence intervals)
• Sample forecasts (distribution samples)
• Custom quantile levels for risk assessment

Installation

Prerequisites

• Node.js 20+
• npm 10+
• FAIM API key: Register at https://faim.it.com/ to get your FAIM_API_KEY

Remote MCP Server — Useful for Workflow Automation Tools like n8n

The MCP server is deployed remotely.

To use the remote MCP server, send requests to the following endpoint:

https://mcp.faim.it.com

Provide your FAIM API key using Bearer authentication.

Local MCP server

Option 1: Install from npm (Recommended)

Configure your client to use it directly with npx:

{
  "mcpServers": {
    "faim": {
      "command": "npx",
      "args": ["-y", "@faim-group/mcp"],
      "env": {
        "FAIM_API_KEY": "your-api-key-here"
      }
    }
  }
}

No installation required - npx will automatically download and run the latest version.

Alternatively, if you prefer to install globally first:

npm install -g @faim-group/mcp

Then in config:

{
  "mcpServers": {
    "faim": {
      "command": "faim-mcp",
      "env": {
        "FAIM_API_KEY": "your-api-key-here"
      }
    }
  }
}

Option 2: Clone and Build Locally

# Clone the repository
git clone <repository-url>
cd faim-mcp

# Install dependencies
npm install

# Build the project
npm run build

# Run tests
npm test

# Run type checker
npm run lint

Then use the local path:

{
  "mcpServers": {
    "faim": {
      "command": "node",
      "args": ["/path/to/faim-mcp/dist/index.js"],
      "env": {
        "FAIM_API_KEY": "your-api-key-here"
      }
    }
  }
}

Examples

n8n Workflow - Demand Forecasting

An example n8n workflow for demand forecasting is available in examples/n8n/demand_forecasting.json. This workflow demonstrates how to integrate the FAIM MCP server with n8n for automated demand forecasting tasks.

To use this example:

1. Open n8n
2. Import the workflow from n8n_examples/demand_forecasting.json
3. Configure your FAIM API key in the MCP connection settings
4. Execute the workflow with your time series data

Configuration

Environment Variables

# Required: Your FAIM API key
export FAIM_API_KEY="your-api-key-here"

# Optional: Set to non-production for verbose logging
export NODE_ENV=development

MCP Compatibility

This server implements the Model Context Protocol (MCP), an open protocol for connecting AI assistants to external tools and data sources. It works with any LLM and application that implements an MCP client.

Using with Any LLM or System

This server implements the standard MCP protocol and works with any application that implements an MCP client:

• Direct MCP client implementation
• AI framework adapters that support MCP
• IDE extensions that expose MCP tools to any LLM
• Custom middleware that translates between MCP and your LLM's tool calling format

Usage

Starting the Server

# Build and start the server
npm run build
node dist/index.js

The server will:

1. Read the API key from environment
2. Initialize the FAIM client
3. Listen on stdin for JSON-RPC requests
4. Send responses to stdout

Tool 1: List Models

Returns available forecasting models and their capabilities.

Request:

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/list",
  "params": {}
}

Response:

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "tools": [
      {
        "name": "list_models",
        "description": "...",
        "inputSchema": { ... }
      },
      {
        "name": "forecast",
        "description": "...",
        "inputSchema": { ... }
      }
    ]
  }
}

Tool 2: Forecast

Performs time series forecasting using FAIM models.

Request (Point Forecast):

{
  "jsonrpc": "2.0",
  "id": 2,
  "method": "tools/call",
  "params": {
    "name": "forecast",
    "arguments": {
      "model": "chronos2",
      "x": [1, 2, 3, 4, 5, 6, 7, 8, 9, 10],
      "horizon": 10,
      "output_type": "point"
    }
  }
}

Request (Quantile Forecast with Confidence Intervals):

{
  "jsonrpc": "2.0",
  "id": 3,
  "method": "tools/call",
  "params": {
    "name": "forecast",
    "arguments": {
      "model": "chronos2",
      "x": [[[100, 50], [102, 51], [105, 52]]],
      "horizon": 5,
      "output_type": "quantiles",
      "quantiles": [0.1, 0.5, 0.9]
    }
  }
}

Response:

{
  "jsonrpc": "2.0",
  "id": 2,
  "result": {
    "success": true,
    "data": {
      "model_name": "chronos2",
      "model_version": "1.0",
      "output_type": "point",
      "forecast": {
        "point": [[[11], [12], [13], ...]]
      },
      "metadata": {
        "token_count": 150,
        "duration_ms": 245
      },
      "shape_info": {
        "input_shape": [1, 10, 1],
        "output_shape": [1, 10, 1]
      }
    }
  }
}

Project Structure

faim-mcp/
├── src/
│   ├── index.ts              # MCP server entry point
│   ├── types.ts              # TypeScript interfaces
│   ├── tools/
│   │   ├── list-models.ts    # List models tool
│   │   └── forecast.ts       # Forecasting tool
│   └── utils/
│       ├── client.ts         # FAIM client singleton
│       ├── validation.ts     # Input validation
│       └── errors.ts         # Error transformation
├── tests/
│   ├── tools/
│   │   ├── list-models.test.ts
│   │   └── forecast.test.ts
│   └── utils/
│       ├── validation.test.ts
│       └── errors.test.ts
├── dist/                     # Built output
│   ├── index.js             # ESM bundle
│   ├── index.cjs            # CommonJS bundle
│   ├── index.d.ts           # Type declarations
│   └── *.map                # Source maps
└── package.json, tsconfig.json, tsup.config.ts, vitest.config.ts

Testing

The project includes comprehensive tests for:

• Input Validation: Valid/invalid inputs, edge cases, boundary values
• Error Handling: SDK errors, JavaScript errors, error classification
• Tool Functionality: Response structure, model availability
• Type Safety: TypeScript compilation, type guards

Run tests:

npm test                 # Run all tests
npm run test:coverage   # Run with coverage report
npm run test:ui         # Run with UI dashboard

Debugging

Enable verbose logging:

NODE_ENV=development node dist/index.js

Output goes to stderr (not interfering with stdout JSON-RPC).

Building and Deployment

Build for Production

npm run build

Outputs:

• dist/index.js - ESM module
• dist/index.cjs - CommonJS module
• dist/index.d.ts - Type declarations
• Source maps for debugging

Deployment Checklist

• Set FAIM_API_KEY environment variable
• Run npm run build
• Run npm test to verify
• Deploy dist/ directory
• Run node dist/index.js as the server process

Troubleshooting

"FAIM_API_KEY not set"

export FAIM_API_KEY="your-key-here"
node dist/index.js

"Module not found" errors

npm install
npm run build

Server not responding

• Check that stdout/stderr are properly connected
• Verify JSON-RPC format of requests
• Check logs for error messages
• Ensure FAIM API is accessible

License

MIT