Skip to main content
Glama
FAIM MCP Server
by S-FM

FAIM MCP Server

npm version License: MIT

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

Related MCP server: Prometheus MCP Server

Installation

Prerequisites

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

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

Available Tools

2 tools
forecastA

Perform time series forecasting using FAIM platform. Supports both point forecasting (single value) and probabilistic forecasting (confidence intervals). Can handle univariate and multivariate time series data. Currently supported models: Chronos2 (default, recommended for multivariate) and TiRex (fast, univariate only).

Inputs: model (required), horizon (required), x, output_type, +2 more.

list_modelsA

List all available forecasting models and their capabilities. Returns information about Chronos2, TiRex, and other available models, including supported output types and features.

Inputs: no named parameters.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A4.2/5.0

    Scored across 2 tools

    Disambiguation5/5

    The two tools serve entirely different purposes: one performs forecasting while the other lists available models. There is no ambiguity or overlap.

    Naming Consistency5/5

    Both tools follow the descriptive verb_noun pattern (forecast, list_models) and use consistent lowercase_with_underscores naming.

    Tool Count2/5

    With only two tools, the server feels underdeveloped for a forecasting platform. Expected tools like data management, evaluation, or model configuration are missing.

    Completeness2/5

    The tool surface is severely incomplete. Typical forecasting workflows require data upload, model training, evaluation, and result retrieval, none of which are present beyond the basic forecast and model listing.

    Maintenance

    ActivityNo data
    ResponsivenessOutdated data

    Related MCP Connectors

    Related MCP Servers

    • F
      license
      B
      quality
      D
      maintenance
      A Model Context Protocol server implementation that can be run directly or through Docker, enabling AI assistants to interact with external systems through the MCP standard.
      2
      -
    • A
      license
      B
      quality
      D
      maintenance
      A Model Context Protocol server that enables AI assistants to query Prometheus metrics, discover available data, and analyze system performance through natural language interactions.
      5
      224 npm
      MIT
    • A
      license
      Not graded
      quality
      D
      maintenance
      An MCP server powered by Meta's Prophet that enables LLMs to perform time-series forecasting, trend analysis, and predictive modeling on historical data. It provides LLM-friendly statistical summaries, automated business-rule validation, and ready-to-render Chart.js visualizations.
      MIT
    • F
      license
      Not graded
      quality
      C
      maintenance
      Model Context Protocol (MCP) server that gives AI assistants a safe, correct data-analyst capability over business metrics - without raw SQL improvisation.
      -