Forecast MCP Server

A Model Context Protocol (MCP) server that connects AI assistants — including Claude and ChatGPT — directly to your Forecast account.

Ask your AI assistant to list projects, log time, manage tasks, check financials, and more — all in plain language.

# Run directly without installing (requires Node 20+)
FORECAST_API_KEY=your-key npx @thedistance/forecast-mcp

Contents

• Prerequisites
• Getting a Forecast API Key
• Installation
• Connect to Claude Desktop
• Connect to Claude Code
• Connect to ChatGPT
• Connect to Other MCP Clients
• Available Tools
• Example Prompts
• Running the Server Manually
• Development
• Troubleshooting

Prerequisites

• Node.js 20 or later — download here
• A Forecast account with API access
• The AI client you want to use (Claude Desktop, Claude Code, ChatGPT Plus/Pro, etc.)

Getting a Forecast API Key

1. Log in to your Forecast account
2. Go to Settings → API (you need admin rights)
3. Click Generate API key
4. Copy the key — you will not be able to see it again

Keep your API key secret. It provides full access to your Forecast account.

Installation

Option A — npx (no install required)

No cloning or building needed. Pass npx @thedistance/forecast-mcp as the command in your MCP client config (see sections below), or run it directly:

FORECAST_API_KEY=your-key npx @thedistance/forecast-mcp

npx will download and cache the package on first run.

Option B — Global install

npm install -g @thedistance/forecast-mcp
FORECAST_API_KEY=your-key forecast-mcp

Option C — Clone and build locally

git clone https://github.com/thedistance/Forecast-mcp.git
cd Forecast-mcp
npm install
npm run build

You now have a built server at dist/index.js.

Connect to Claude Desktop

Claude Desktop supports local MCP servers via its configuration file.

1. Find the config file

| Platform | Path | |----------|------| | macOS | ~/Library/Application Support/Claude/claude_desktop_config.json | | Windows | %APPDATA%\Claude\claude_desktop_config.json |

2. Add the server

Open (or create) the file and add the forecast entry inside mcpServers.

Recommended — via npx (no local install needed):

{
  "mcpServers": {
    "forecast": {
      "command": "npx",
      "args": ["-y", "@thedistance/forecast-mcp"],
      "env": {
        "FORECAST_API_KEY": "your-api-key-here"
      }
    }
  }
}

Alternative — from a local clone:

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

3. Restart Claude Desktop

Quit and reopen Claude Desktop. You should see forecast listed under MCP servers in the menu (look for the plug icon or check Settings → MCP).

4. Try it

Type in Claude Desktop:

"List all my running projects in Forecast"

Connect to Claude Code

Claude Code is Anthropic's CLI tool. MCP servers can be added per-project or globally.

Option A — Project-level (.claude/settings.json)

Create or edit .claude/settings.json in your project root:

{
  "mcpServers": {
    "forecast": {
      "command": "npx",
      "args": ["-y", "@thedistance/forecast-mcp"],
      "env": {
        "FORECAST_API_KEY": "your-api-key-here"
      }
    }
  }
}

Option B — Global (~/.claude/settings.json)

Same format but placed in your home directory — makes the server available in every Claude Code session.

Option C — CLI flag

claude --mcp-server 'forecast:npx @thedistance/forecast-mcp' \
  --env FORECAST_API_KEY=your-api-key-here

Verify it's connected

In a Claude Code session run:

/mcp

You should see forecast listed with its tools.

Connect to ChatGPT

ChatGPT (Plus/Pro/Team) supports remote MCP servers over HTTPS. The server must be publicly accessible — it cannot run locally on your machine the way Claude Desktop can.

Step 1 — Run the server in HTTP mode

The server supports an HTTP transport mode:

FORECAST_API_KEY=your-api-key-here MCP_TRANSPORT=http PORT=3000 node dist/index.js
# or
FORECAST_API_KEY=your-api-key-here node dist/index.js --http

The server will listen on http://0.0.0.0:3000/mcp.

Step 2 — Expose it publicly

You need the server running somewhere with a public HTTPS URL. Options:

A) Deploy to a cloud platform

Recommended for production. The server is a standard Node.js app. Deploy to Railway, Render, Fly.io, or any VPS:

# Example: Railway
railway up

# Example: Render — set env vars FORECAST_API_KEY and MCP_TRANSPORT=http in dashboard

Set these environment variables on the platform:

• FORECAST_API_KEY — your Forecast API key
• MCP_TRANSPORT=http
• PORT — the port your host expects (usually set automatically)

B) Local tunnel for testing (not for production)

Use ngrok or Cloudflare Tunnel to expose your local server temporarily:

# Terminal 1 — start the server
FORECAST_API_KEY=your-api-key-here node dist/index.js --http

# Terminal 2 — expose it
ngrok http 3000
# Note the https URL, e.g. https://abc123.ngrok-free.app

Step 3 — Add to ChatGPT

1. Open ChatGPT and go to Settings
2. Navigate to Connectors → Add connector (or Tools → MCP)
3. Enter your server URL: https://your-domain.com/mcp
4. ChatGPT will discover the available tools automatically

Step 4 — Try it

Start a new conversation and ask:

"Show me all active projects in Forecast"

Connect to Other MCP Clients

Cursor

Add to ~/.cursor/mcp.json (or .cursor/mcp.json in your project):

{
  "mcpServers": {
    "forecast": {
      "command": "npx",
      "args": ["-y", "@thedistance/forecast-mcp"],
      "env": {
        "FORECAST_API_KEY": "your-api-key-here"
      }
    }
  }
}

Windsurf

Add to ~/.codeium/windsurf/mcp_config.json:

{
  "mcpServers": {
    "forecast": {
      "command": "npx",
      "args": ["-y", "@thedistance/forecast-mcp"],
      "env": {
        "FORECAST_API_KEY": "your-api-key-here"
      }
    }
  }
}

Any MCP-compatible client (HTTP)

Point your client at:

POST https://your-host/mcp
Content-Type: application/json

The server implements the MCP Streamable HTTP transport in stateless mode — one session per request.

Available Tools

Projects

| Tool | Description | |------|-------------| | forecast_list_projects | List all projects. Pass includeProgress: true for % complete | | forecast_get_project | Get a single project by ID | | forecast_create_project | Create a new project | | forecast_update_project | Update project details (name, stage, status, dates, etc.) | | forecast_delete_project | Permanently delete a project | | forecast_get_project_financials | Get budget, spend, and revenue summary for a project |

Tasks

| Tool | Description | |------|-------------| | forecast_list_tasks | List tasks, optionally filtered by project or updated-after date (paginated) | | forecast_get_task | Get a single task by ID | | forecast_create_task | Create a task in a project with optional estimates and assignments | | forecast_update_task | Update task details, assignments, priority, or dates | | forecast_delete_task | Permanently delete a task | | forecast_list_task_comments | List all comments on a task | | forecast_create_task_comment | Add a comment to a task |

Persons

| Tool | Description | |------|-------------| | forecast_list_persons | List all team members | | forecast_get_person | Get a person by ID | | forecast_create_person | Add a new team member (requires email and profile) | | forecast_update_person | Update a person's details | | forecast_delete_person | Remove a person from the account |

Time Registrations

| Tool | Description | |------|-------------| | forecast_list_time_registrations | List time entries, filterable by person/project/date (paginated) | | forecast_get_time_registration | Get a single time entry by ID | | forecast_create_time_registration | Log time for a person on a project or task | | forecast_update_time_registration | Edit a time entry | | forecast_delete_time_registration | Delete a time entry |

Allocations

| Tool | Description | |------|-------------| | forecast_list_allocations | List resource allocations, filterable by person/project/date | | forecast_get_allocation | Get a single allocation by ID | | forecast_create_allocation | Book a person on a project for a date range (per-day minutes) | | forecast_update_allocation | Update an allocation | | forecast_delete_allocation | Delete an allocation |

Clients

| Tool | Description | |------|-------------| | forecast_list_clients | List all clients | | forecast_get_client | Get a client by ID | | forecast_create_client | Create a new client | | forecast_update_client | Update client details | | forecast_delete_client | Delete a client |

Example Prompts

Below are natural-language prompts you can use once connected.

Projects

• "List all projects that are currently running"
• "Show me the budget and spend for project 42"
• "Create a new project called 'Website Redesign' for client Acme Corp"
• "Mark project 123 as DONE"

Tasks

• "Show me all high-priority tasks in project 55"
• "Create a task 'Fix login bug' in project 42, estimated 2 hours, assign to person 7"
• "What tasks were updated in the last 7 days?"
• "Add a comment to task 999 saying 'Ready for review'"

Time

• "Log 2 hours for person 7 on project 42 for today"
• "Show me all time logged by Alice last week"
• "How many hours were logged on project 55 in January?"

Allocations

• "Book Alice on project 42 for the next two weeks, 8 hours a day Monday to Friday"
• "Show me all allocations for the design team next month"
• "Remove the allocation with ID 300"

People & Clients

• "List all active team members"
• "Add a new client called 'Mega Corp'"
• "Who is person 389664?"

Running the Server Manually

Via npx

# stdio mode (default)
FORECAST_API_KEY=your-key npx @thedistance/forecast-mcp

# HTTP mode
FORECAST_API_KEY=your-key MCP_TRANSPORT=http PORT=3000 npx @thedistance/forecast-mcp
# or with flag
FORECAST_API_KEY=your-key npx @thedistance/forecast-mcp --http

From a local clone

FORECAST_API_KEY=your-key npm start               # stdio
FORECAST_API_KEY=your-key npm run dev             # dev mode, no build needed
FORECAST_API_KEY=your-key node dist/index.js --http  # HTTP mode

The HTTP server exposes a single endpoint: POST /mcp

Development

Project layout

src/
├── index.ts                    # Entry point — stdio or HTTP transport
├── client.ts                   # Forecast HTTP client with proxy support
├── types.ts                    # Zod input schemas shared across tools
└── tools/
    ├── projects.ts
    ├── tasks.ts
    ├── persons.ts
    ├── time-registrations.ts
    ├── allocations.ts
    └── clients.ts

Adding a new resource

1. Add Zod schemas to src/types.ts
2. Create src/tools/your-resource.ts following the pattern in existing files
3. Export registerYourResourceTools(server: McpServer)
4. Import and call it in src/index.ts
5. Follow the naming convention: forecast_{resource}_{action}

Scripts

npm run build   # Compile TypeScript → dist/
npm run dev     # Run with tsx (no build needed, stdio mode)
npm start       # Run compiled server

Testing with MCP Inspector

FORECAST_API_KEY=your-key npx @modelcontextprotocol/inspector node dist/index.js

This opens a browser UI where you can browse and call tools interactively.

Publishing to npm

The prepublishOnly script runs the build automatically. To publish:

# 1. Log in to npm (one-time)
npm login

# 2. Bump the version
npm version patch   # or minor / major

# 3. Publish (builds automatically via prepublishOnly)
npm publish --access public

The published package includes only dist/, README.md, and LICENSE — no source files.

To preview exactly what will be published before pushing:

npm pack --dry-run

Troubleshooting

"FORECAST_API_KEY environment variable is not set"

The server requires your API key at startup. Make sure you pass it:

FORECAST_API_KEY=your-key node dist/index.js

Or set it in the env block of your MCP client config (see setup sections above).

Claude Desktop doesn't show the Forecast server

• Check that the path in args is absolute and the file exists: ls /your/path/to/Forecast-mcp/dist/index.js
• Validate your JSON config — a trailing comma or missing brace will silently break it
• Fully quit and relaunch Claude Desktop (⌘Q on macOS, not just close the window)

Tools work in Claude but not in ChatGPT

ChatGPT only supports remote HTTPS servers. Make sure:

• The server is running with MCP_TRANSPORT=http
• It is deployed to a publicly accessible host (not localhost)
• The URL you entered in ChatGPT ends in /mcp

"fetch failed" or network errors

If you are running behind a corporate proxy, set the proxy env var before starting:

HTTPS_PROXY=http://proxy.example.com:8080 FORECAST_API_KEY=your-key npm start

The server automatically detects HTTPS_PROXY / https_proxy and routes requests through it.

API returns 401 Unauthorized

Your API key is invalid or has been disabled. Regenerate it in Forecast → Settings → API.

Getting verbose logs

Set DEBUG=* to see all MCP protocol messages:

DEBUG=* FORECAST_API_KEY=your-key npm start

API Reference

• Forecast REST API docs: https://github.com/Forecast-it/API
• Base URL: https://api.forecast.it/api/v1/
• Authentication header: X-FORECAST-API-KEY
• MCP specification: https://modelcontextprotocol.io