@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:

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