freelo-mcp

A Model Context Protocol (MCP) server built with mcp-framework that provides integration with Freelo project management API.

Features

This MCP server exposes tools for interacting with Freelo tasks, subtasks, and files:

• freelo_get_task - Get detailed information about a task including comments and attached files

• freelo_list_task_subtasks - List all subtasks with completion status

• freelo_download_file - Download files from task comments using UUID

Quick Start

1. Get Your Freelo API Key

1. Log in to your Freelo Dashboard

2. Click on your avatar in the top right corner → Settings

3. Scroll to the bottom to find your API Key

2. Add to Claude Code

That's it! You can now use Freelo tools in Claude Code.

Alternative Setup

Claude Code (Manual)

Add to your MCP settings (~/.claude/settings.json or project .mcp.json):

Claude Desktop

Add to Claude Desktop configuration file:

MacOS: ~/Library/Application Support/Claude/claude_desktop_config.json Windows: %APPDATA%/Claude/claude_desktop_config.json

Development

For local development, configure Claude to use the built project directly:

Project Structure

Available Tools

1. freelo_get_task

Get detailed information about a specific Freelo task, including all comments and attached files.

Parameters:

• taskId (number) - The unique ID of the task

Returns:

• Task name, description, priority, state

• Author and assignee information

• Dates (created, due, completed)

• Project and task list details

• Tags and time estimates

• Comments with content, author, timestamps, and attached files (with UUIDs)

Example:

2. freelo_list_task_subtasks

List all subtasks of a specific task with completion statistics.

Parameters:

• taskId (number) - The unique ID of the task

Returns:

• Array of subtasks with names, state, dates, author, assignee

• Statistics (total, completed, remaining, completion percentage)

Example:

3. freelo_download_file

Download a file from Freelo using its UUID. File UUIDs are found in task comments (use freelo_get_task first).

Parameters:

• fileUuid (string) - The UUID of the file (from task comments)

• filename (string, optional) - Custom filename to save as

Returns:

• Downloaded file path (in system temp directory)

• File metadata (UUID, filename, size)

Example:

Adding New Tools

You can extend this MCP server with additional Freelo API tools:

Tool Development

Example tool structure:

Publishing to npm

1. Update your package.json:

   • Ensure name is unique and follows npm naming conventions

   • Set appropriate version

   • Add description, author, license, etc.

   • Check bin points to the correct entry file

2. Build and test locally:

   npm run build npm link freelo-mcp # Test your CLI locally

3. Login to npm (create account if necessary):

   npm login

4. Publish your package:

   npm publish

After publishing, users can add it to their Claude Desktop client (see below) or run it with npx.

Usage with Claude Desktop

After building the project and configuring your credentials (see Freelo API Setup), restart Claude Desktop to load the MCP server.

You can then use the Freelo tools in your conversations with Claude:

Example conversation:

Building and Testing

1. Make changes to your tools

2. Run npm run build to compile

3. The server will automatically load your tools on startup

Learn More

MCP Framework

• MCP Framework GitHub

• MCP Framework Docs

• Model Context Protocol

Freelo API

• Freelo API Documentation - Official API reference

• Freelo API Help - How to get your API key

• Freelo Website - Project management platform

API Reference

This MCP server uses the Freelo REST API v1:

• Base URL: https://api.freelo.io/v1

• Authentication: HTTP Basic Auth (email:apiKey)

• Response Format: JSON

• Current Support: Read-only operations (GET endpoints)

For detailed API specifications, see the official Freelo API documentation.

Contributing

This is a personal project for Freelo API integration. Feel free to extend it with additional tools or improvements.

License

MIT