freelo-mcp-server

@sesonet/freelo-mcp-server

MCP (Model Context Protocol) server for Freelo project management API.

Key Features:

• 33 curated tools (reduced from 98 in original)
• Readonly mode by default (--readonly flag)
• Audit logging (JSONL + optional webhook)
• All MCP clients supported (Claude Code, Cursor, VS Code, etc.)

Fork of karlost/FreeloMCP.

Installation

Note: This package is not published to npm registry. Install directly from GitHub.

# Install globally from GitHub
npm install -g github:sesonet/freelo-mcp-server

Quick Start

# Set credentials
export FREELO_EMAIL="your@email.com"
export FREELO_API_KEY="your-api-key"

# Run in readonly mode (default)
freelo-mcp-server

# Run with all tools (including edit operations)
FREELO_READONLY=false freelo-mcp-server

Documentation

• Installation Guide - Detailed setup for all clients
• Tools Reference - Complete list of available tools
• Configuration - Environment variables and options

Tool Categories

| Category | Tools | Description | |----------|-------|-------------| | Projects | 4 | List, details, workers | | Tasks | 11 | CRUD, finish, activate, templates | | Tasklists | 2 | List, details | | Subtasks | 2 | List, create | | Comments | 1 | List all comments | | Notes | 3 | Get, create, update | | Users | 2 | List, assignable workers | | Time Tracking | 2 | Start, stop timer | | Work Reports | 3 | List, create, update | | Search | 2 | Elasticsearch, custom filters | | States | 1 | List task states |

Total: 33 tools (20 readonly + 13 edit)

Modes

Readonly Mode (Default)

FREELO_READONLY=true freelo-mcp-server

Only 20 read-only tools available. Safe for browsing and reporting.

Full Mode

FREELO_READONLY=false freelo-mcp-server

All 33 tools available including create, update, and finish operations.

Audit Logging

All tool calls are logged to audit.jsonl:

{"timestamp":"2025-01-12T10:30:00.000Z","tool":"freelo_get_projects","params":{},"status":"success","durationMs":245}

Configure via environment: ``bash FREELO_AUDIT_LOG=./logs/audit.jsonl # Log file path FREELO_AUDIT_WEBHOOK=https://... # Optional webhook URL FREELO_AUDIT_ENABLED=false # Disable logging ``

Environment Variables

| Variable | Required | Description | |----------|----------|-------------| | FREELO_EMAIL | Yes | Freelo account email | | FREELO_API_KEY | Yes | Freelo API key | | FREELO_USER_AGENT | No | Custom User-Agent | | FREELO_READONLY | No | Enable readonly mode | | FREELO_AUDIT_LOG | No | Audit log path | | FREELO_AUDIT_WEBHOOK | No | Webhook URL | | FREELO_AUDIT_ENABLED | No | Enable/disable audit |

Client Configuration

Claude Code (CLI)

Add to ~/.claude.json (macOS/Linux) or %USERPROFILE%\.claude.json (Windows):

{
  "mcpServers": {
    "freelo": {
      "type": "stdio",
      "command": "freelo-mcp-server",
      "env": {
        "FREELO_EMAIL": "your@email.com",
        "FREELO_API_KEY": "your-api-key",
        "FREELO_READONLY": "true"
      }
    }
  }
}

Other Clients

See Installation Guide for Cursor, VS Code, Windsurf, and Continue.dev setup.

License

MIT License - see LICENSE for details.

Dual copyright:

• Original: (c) 2024 Chodeec
• Fork: (c) 2025 sesonet