FreeAgent

This MCP server lets Claude interact with your FreeAgent account to manage timeslips and timers, with automatic OAuth handling and Docker support for easy deployment.

How to use

You use this server by configuring an MCP client to connect either locally via a standard input/output (stdio) flow or remotely in a containerized environment. Once connected, you can list, create, update, and delete timeslips, start and stop timers, and rely on automatic OAuth token refresh to keep access seamless. The server exposes a well-defined set of actions you can invoke from your MCP client to manage your FreeAgent data without leaving your workflow.

How to install

Prerequisites you need before you start include Node.js 18+ for direct Node.js usage and Docker plus Docker Compose for containerized usage. You also need a FreeAgent account with API access and OAuth credentials from the FreeAgent Developer Dashboard.

# Option 1: Direct Node.js Installation

# 1. Clone the repository
git clone https://github.com/yourusername/freeagent-mcp.git
cd freeagent-mcp

# 2. Install dependencies
npm install

# 3. 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

# 2. Create your environment file
cp .env.example .env
# Edit .env with your FreeAgent credentials

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

Configuration

Configure the MCP client to connect to the FreeAgent MCP server by adding an entry for the FreeAgent server in your MCP settings. The following snippets show the required JSON configurations for the stdio (Node.js) and Docker deployments.

{
  "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": []
    }
  }
}

{
  "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": []
    }
  }
}

Notes and tips

The server supports direct Node.js usage or containerized deployment via Docker. Ensure your FreeAgent OAuth tokens are kept secure and refreshed automatically to avoid interrupted access. If you plan to run locally, point your MCP client to the stdio server using the specified command and environment variables. If you prefer containerization, build and run the Docker image and supply the same environment values.

Available tools

list_timeslips

Retrieve and filter timeslips with optional nested resources, date ranges, and status filters.

create_timeslip

Create a new timeslip linked to a task, user, and project with the specified date and hours.

update_timeslip

Modify existing timeslip details such as hours, date, or comments.

start_timer

Start a timer for a specific timeslip or task.

stop_timer

Stop an active timer to record time against a timeslip.

delete_timeslip

Remove a timeslip from the account.

oauth_token_refresh

Automatically refresh OAuth tokens to maintain access without manual intervention.

docker_support

Dockerized deployment support for easy containerized usage.