Skip to main content
Glama
Sign In
enesjakozh
FreeAgent MCP Server

FreeAgent MCP Server

by markpitt
OverviewSchemaSourceRelated ServersDiscussionsAdmin
JavaScript
Remote

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.

License: MIT

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

Related MCP server: freshbooks-mcp-server

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

  1. Clone the repository:

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

  1. Install dependencies:

npm install

  1. 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

  1. Clone the repository:

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

  1. Create your environment file:

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

  1. 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

  1. Fork the repository

  2. Create your feature branch (git checkout -b feature/amazing-feature)

  3. Commit your changes (git commit -am 'Add some amazing feature')

  4. Push to the branch (git push origin feature/amazing-feature)

  5. 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

Available Tools

7 tools
create_timeslipC

Create a new timeslip

Inputs: task (required), user (required), project (required), dated_on (required), +2 more.

delete_timeslipC

Delete a timeslip

Inputs: id (required).

get_timeslipC

Get a single timeslip by ID

Inputs: id (required).

list_timeslipsC

List timeslips with optional filtering

Inputs: from_date, to_date, updated_since, view, +4 more.

start_timerC

Start a timer for a timeslip

Inputs: id (required).

stop_timerC

Stop a running timer for a timeslip

Inputs: id (required).

update_timeslipC

Update an existing timeslip

Inputs: id (required), task, user, project, +3 more.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    Deploy Server
    Claude Code, inside the Godot 4 editorFlockbay puts an AI agent in the real Godot 4 editor: it writes GDScript, runs your game and fixes what breaks. Free, or bring your own Claude Code or Codex.flockbay.comAd

    TDQS

    A3.5/5.0

    Scored across 7 tools

    Disambiguation5/5

    Each tool has a clearly distinct purpose with no ambiguity. The tools cover specific actions (create, delete, get, list, start timer, stop timer, update) on the 'timeslip' resource, making it easy for an agent to select the correct tool for any required operation without confusion.

    Naming Consistency5/5

    All tool names follow a consistent verb_noun pattern (e.g., create_timeslip, delete_timeslip). The naming is uniform across all tools, using snake_case and clear action verbs, which enhances predictability and readability for agents.

    Tool Count5/5

    With 7 tools, the count is well-scoped for managing timeslips, covering essential CRUD operations and timer functionality. Each tool serves a distinct and necessary role, making the set neither too sparse nor overloaded for the domain.

    Completeness5/5

    The tool set provides complete coverage for the timeslip domain, including full CRUD operations (create, get, list, update, delete) and additional lifecycle features (start and stop timer). There are no obvious gaps, ensuring agents can handle all expected workflows without dead ends.

    Maintenance

    ActivityInactive
    ResponsivenessNo recent community issues

    Resources

    Related MCP Connectors

    Related MCP Servers

    • freshbooks-mcp-server

      bitovi
      F
      license
      Not graded
      quality
      C
      maintenance
      An MCP server that connects Claude to FreshBooks, enabling reading and management of invoices, clients, expenses, projects, and time entries via natural language.
      1
      -

    • OpenProject MCP Server

      Morrisdev
      A
      license
      Not graded
      quality
      D
      maintenance
      An MCP server that connects Claude Desktop to your OpenProject instance, allowing you to manage projects, tasks, and time entries through natural language.
      MIT

    • FreshBooks MCP Server

      SGTCS26
      F
      license
      Not graded
      quality
      D
      maintenance
      An MCP server for the FreshBooks API that lets Claude read and manage invoices, clients, expenses, projects, services, payments, and time entries.
      -