FreeAgent MCP Server

A Claude MCP (Model Context Protocol) server for managing FreeAgent timeslips and timers. This server allows Claude to interact with your FreeAgent account to track time, manage timers, and handle timeslip operations.

Features

List and filter timeslips with nested data
Create new timeslips
Update existing timeslips
Start and stop timers
Delete timeslips
Automatic OAuth token refresh
Comprehensive error handling
Docker support

Prerequisites

Node.js 18+ (for direct Node.js usage)
Docker & Docker Compose (for containerized usage)
A FreeAgent account with API access
OAuth credentials from the FreeAgent Developer Dashboard

Installation

Option 1: Direct Node.js Installation

Clone the repository:

git clone https://github.com/yourusername/freeagent-mcp.git
cd freeagent-mcp

Install dependencies:

npm install

Get your OAuth tokens:

# Set your FreeAgent credentials
export FREEAGENT_CLIENT_ID="your_client_id"
export FREEAGENT_CLIENT_SECRET="your_client_secret"

# Run the OAuth setup script
node scripts/get-oauth-tokens.js

Option 2: Docker Installation

Clone the repository:

git clone https://github.com/yourusername/freeagent-mcp.git
cd freeagent-mcp

Create your environment file:

cp .env.example .env
# Edit .env with your FreeAgent credentials

Build Docker image:

docker build -t freeagent-mcp .

Configuration

Add the server to your MCP settings (typically in %APPDATA%/Code/User/globalStorage/saoudrizwan.claude-dev/settings/cline_mcp_settings.json):

For Node.js Installation:

{
  "mcpServers": {
    "freeagent": {
      "command": "node",
      "args": ["path/to/freeagent-mcp/build/index.js"],
      "env": {
        "FREEAGENT_CLIENT_ID": "your_client_id",
        "FREEAGENT_CLIENT_SECRET": "your_client_secret",
        "FREEAGENT_ACCESS_TOKEN": "your_access_token",
        "FREEAGENT_REFRESH_TOKEN": "your_refresh_token"
      },
      "disabled": false,
      "autoApprove": []
    }
  }
}

For Docker Installation:

{
  "mcpServers": {
    "freeagent": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "-e", "FREEAGENT_CLIENT_ID",
        "-e", "FREEAGENT_CLIENT_SECRET",
        "-e", "FREEAGENT_ACCESS_TOKEN",
        "-e", "FREEAGENT_REFRESH_TOKEN",
        "freeagent-mcp"
      ],
      "env": {
        "FREEAGENT_CLIENT_ID": "your_client_id",
        "FREEAGENT_CLIENT_SECRET": "your_client_secret",
        "FREEAGENT_ACCESS_TOKEN": "your_access_token",
        "FREEAGENT_REFRESH_TOKEN": "your_refresh_token"
      },
      "disabled": false,
      "autoApprove": []
    }
  }
}

Usage

Once configured, Claude can use the following tools:

List Timeslips

{
  "from_date": "2024-01-01",      // Start date (YYYY-MM-DD)
  "to_date": "2024-03-04",        // End date (YYYY-MM-DD)
  "updated_since": "2024-03-04T12:00:00Z",  // ISO datetime
  "view": "all",                  // "all", "unbilled", or "running"
  "user": "https://api.freeagent.com/v2/users/123",
  "task": "https://api.freeagent.com/v2/tasks/456",
  "project": "https://api.freeagent.com/v2/projects/789",
  "nested": true                  // Include nested resources
}

Create Timeslip

{
  "task": "https://api.freeagent.com/v2/tasks/123",
  "user": "https://api.freeagent.com/v2/users/456",
  "project": "https://api.freeagent.com/v2/projects/789",
  "dated_on": "2024-03-04",
  "hours": "1.5",
  "comment": "Optional comment"
}

Timer Controls

// Start timer
{
  "id": "123"
}

// Stop timer
{
  "id": "123"
}

Development

Node.js Development

# Build the project
npm run build

# Watch for changes
npm run watch

# Run tests (when implemented)
npm test

Docker Development

# Build the Docker image
docker build -t freeagent-mcp .

Contributing

Fork the repository
Create your feature branch (git checkout -b feature/amazing-feature)
Commit your changes (git commit -am 'Add some amazing feature')
Push to the branch (git push origin feature/amazing-feature)
Open a Pull Request

License

This project is licensed under the MIT License - see the LICENSE file for details.

Acknowledgments

FreeAgent for their excellent API documentation
The Claude team for the MCP SDK

Install Server

HTTP connection URL

security – no known vulnerabilities

license - permissive license

quality - confirmed to work

How are these scores calculated?

remote-capable server

The server can be hosted and run remotely because it primarily relies on remote services or has no dependency on the local environment.

Tools

A Claude MCP server that allows Claude to interact with your FreeAgent account to track time, manage timers, and handle timeslip operations.

Related Resources

Reddit Discussion about this server

Related MCP Servers

ticktick-mcp-server
jacepark12
-
security
F
license
-
quality
A MCP server for TickTick that enables interacting with your TickTick task management system directly through Claude and other MCP clients.
Last updated -
56
Python
Port MCP Server
port-labs
-
security
A
license
-
quality
An MCP server that enables Claude to interact with Port.io's AI agent, allowing users to trigger the agent with prompts and receive structured responses including status, output, and action items.
Last updated -
8
Python
MIT License
MCP Claude Code
SDGLBL
-
security
A
license
-
quality
An MCP server that implements Claude Code-like functionality, allowing the AI to analyze codebases, modify files, execute commands, and manage projects through direct file system interactions.
Last updated -
224
Python
MIT License
Union MCP
unionai-oss
-
security
-
license
-
quality
An MCP server that allows Claude models to use Union tasks, workflows, and apps as tools in conversations.
Last updated -
3
Python
Apache 2.0

View all related MCP servers

FreeAgent MCP Server