Nixtla MCP Server

MCP server for multitenant Nixtla TimeGPT forecasting with fine-tuning, rolling backtests, and comprehensive usage tracking.

Features

• 🔐 Multitenant Auth: Token-based authentication with organization isolation
• 🎯 Fine-tuning: Train and manage organization-specific models with metadata
• 🤖 Smart Base Model Selection: Automatically selects timegpt-1 or timegpt-1-long-horizon based on data characteristics
• 📊 Rolling Backtest: Prove fine-tuned models outperform baseline
• 🚨 Anomaly Detection: Detect anomalies with baseline or finetuned models
• 📈 Usage Tracking: Granular consumption tracking with performance metrics
• 🌐 HTTP MCP: JSON-RPC 2.0 over HTTPS (not stdio)
• 🏢 Unified Organization Management: Models, tokens, and configs in one place
• 💾 Blob Storage: Secure 30-day TTL storage with organization-based access control
• 🔮 X_future Support: Use future exogenous variables for better forecasts

Quick Start

1. Deploy to Vercel

Or manually:

# Clone the repository
git clone https://github.com/VaclavRut/nixtla-mcp.git
cd nixtla-mcp

# Install dependencies
npm install

# Deploy to Vercel
vercel

2. Set Environment Variables

In your Vercel project settings, add these environment variables:

# Nixtla API Key (get from https://dashboard.nixtla.io)
NIXTLA_API_KEY=your_nixtla_api_key_here

# HMAC secret for hashing authentication tokens (generate a strong random string)
MCP_AUTH_TOKEN_SECRET=your_strong_random_secret_here

# Admin token for bootstrap endpoint (generate a strong random string)
ADMIN_SETUP_TOKEN=your_admin_token_here

# MongoDB connection string (MongoDB Atlas or your own MongoDB instance)
MONGODB_URI=mongodb+srv://username:[email protected]/?retryWrites=true&w=majority

# Vercel Blob storage token (for storing forecast/anomaly results)
BLOB_READ_WRITE_TOKEN=your_vercel_blob_token_here

Generating Secure Secrets:

# Generate random secrets (run these in your terminal)
node -e "console.log(require('crypto').randomBytes(32).toString('base64'))"

3. Set Up MongoDB

You have two options:

Option A: MongoDB Atlas (Recommended - Free tier available)

1. Go to MongoDB Atlas
2. Create a free cluster
3. Create a database user
4. Whitelist Vercel's IP addresses (or use 0.0.0.0/0 for all IPs)
5. Get your connection string and add it to MONGODB_URI

Option B: Self-hosted MongoDB

# Install MongoDB locally or use Docker
docker run -d -p 27017:27017 --name mongodb mongo:latest

# Connection string for local MongoDB
MONGODB_URI=mongodb://localhost:27017/nixtla-mcp

4. Set Up Vercel Blob Storage

1. Go to your Vercel project dashboard
2. Navigate to Storage → Create Database → Blob
3. Copy the BLOB_READ_WRITE_TOKEN and add it to environment variables

5. Bootstrap Your First Organization

After deploying, create your first organization:

curl -X POST https://your-deployment.vercel.app/api/admin/bootstrap-company \
  -H "Authorization: Bearer YOUR_ADMIN_SETUP_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "orgId": "my-organization"
  }'

Response:

{
  "orgId": "my-organization",
  "authToken": "abc123xyz...",
  "message": "Organization bootstrapped successfully. Store the authToken securely - it will not be shown again."
}

⚠️ Important: Save the authToken - it's returned only once and is needed for all API calls!

Architecture

AI Agent (Claude, GPT, etc.)
    ↓ HTTP POST with Bearer token
MCP Server (Vercel)
    ↓ Auth via MongoDB → Organization resolution
    ↓ Load dataset from URL or inline data
    ↓ Call Nixtla TimeGPT API
    ↓ Track granular usage → MongoDB
    ↓ Store results → Vercel Blob (30-day TTL)
    ↓ Return JSON-RPC response with download URLs

Dataset Format

Datasets can be provided via datasetUrl (URL or blob storage path) or datasetData (inline JSON) in Nixtla multi-series format:

{
  "series": {
    "y": [100, 105, 110, 108, 112, 115],
    "sizes": [3, 3],
    "X": [[1.0, 2.0], [1.1, 2.1], [1.2, 2.2], [1.3, 2.3], [1.4, 2.4], [1.5, 2.5]],
    "X_future": [[1.6, 2.6], [1.7, 2.7]]
  },
  "freq": "D",
  "meta": {
    "seriesNames": ["series_a", "series_b"],
    "timestamps": ["2024-01-01", "2024-01-02", "2024-01-03"]
  }
}

• y: Concatenated values across all series (historical)
• sizes: Length of each series (must sum to y.length)
• X: Optional exogenous variables (historical, same length as y)
• X_future: Optional future exogenous variables for forecast period
• freq: D=Daily, H=Hourly, W=Weekly, M=Monthly, MS=Month Start

MCP Tools

Authentication

All MCP requests require:

POST https://your-deployment.vercel.app/mcp
Authorization: Bearer <YOUR_AUTH_TOKEN>
Content-Type: application/json

Available Tools

#### 1. validate_dataset

Validate dataset format before forecasting.

#### 2. finetune_model

Fine-tune a model on your data with automatic base model selection:

{
  "jsonrpc": "2.0",
  "id": "3",
  "method": "tools/call",
  "params": {
    "name": "finetune_model",
    "arguments": {
      "datasetUrl": "https://blob.vercel-storage.com/...",
      "finetuneOptions": {
        "model": "timegpt-1-long-horizon",  // Optional: override auto-selection
        "finetune_steps": 300,
        "finetune_loss": "mae",
        "finetune_depth": 4,
        "output_model_id": "my-custom-model"
      }
    }
  }
}

Smart Base Model Selection:

• Auto-selected by default based on average series length
• Manual override available via model parameter
• Automatically runs rolling backtest to validate improvement

#### 3. forecast

Generate forecasts using your organization's active model or baseline:

{
  "jsonrpc": "2.0",
  "id": "4",
  "method": "tools/call",
  "params": {
    "name": "forecast",
    "arguments": {
      "datasetUrl": "https://blob.vercel-storage.com/...",
      "h": 14,
      "level": [80, 95],
      "feature_contributions": true
    }
  }
}

Returns: JSON and CSV download URLs (30-day expiration)

#### 4. anomaly_detect

Detect anomalies in time series data:

{
  "jsonrpc": "2.0",
  "id": "5",
  "method": "tools/call",
  "params": {
    "name": "anomaly_detect",
    "arguments": {
      "datasetUrl": "https://blob.vercel-storage.com/...",
      "useFinetunedModel": true,
      "params": {
        "level": 99,
        "clean_ex_first": true
      }
    }
  }
}

#### 5. list_org_models

List all fine-tuned models for your organization.

Connecting AI Agents

Claude Desktop

Add to your Claude Desktop config (~/Library/Application Support/Claude/claude_desktop_config.json on macOS):

{
  "mcpServers": {
    "nixtla": {
      "url": "https://your-deployment.vercel.app/mcp",
      "transport": "http",
      "headers": {
        "Authorization": "Bearer YOUR_AUTH_TOKEN"
      }
    }
  }
}

Custom Integration

import requests

MCP_SERVER_URL = "https://your-deployment.vercel.app/mcp"
AUTH_TOKEN = "your-auth-token"

response = requests.post(
    MCP_SERVER_URL,
    headers={"Authorization": f"Bearer {AUTH_TOKEN}"},
    json={
        "jsonrpc": "2.0",
        "id": "1",
        "method": "tools/call",
        "params": {
            "name": "forecast",
            "arguments": {
                "datasetUrl": "https://blob.vercel-storage.com/...",
                "h": 14
            }
        }
    }
)

print(response.json())

Development

# Install dependencies
npm install

# Run type checking
npm run build

# Run locally (requires environment variables)
vercel dev

Security Features

• Hashed tokens: Raw tokens never stored, only HMAC hashes
• Organization isolation: All data scoped by orgId with MongoDB indexes
• Permission system: Admin vs user access controls
• Idempotency: Prevents duplicate usage charges via request IDs
• Secure blob storage: 30-day TTL with organization-scoped access

License

MIT

Contributing

Contributions are welcome! Please open an issue or submit a pull request.

Support

• Issues: GitHub Issues
• Documentation: Full API Reference
• Nixtla Docs: https://docs.nixtla.io