What can you do with this server?

The FreeAgent MCP Server enables interaction with your FreeAgent account for time tracking and timeslip management. You can: * List and filter timeslips by date range, user, task, project, view type, or updated since * Retrieve, create, update, and delete individual timeslips * Start and stop timers associated with specific timeslips * Include nested resources in timeslip listings * Manage OAuth tokens and authentication automatically * Deploy via Node.js directly or using Docker

Which integrations are available for this server?

Provides integration with FreeAgent accounting software, enabling time tracking through timeslips and timers, including listing, filtering, creating, updating, and deleting timeslips, as well as starting and stopping timers.

How do I use FreeAgent MCP Server?

1. Click on "Install Server". 2. Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state. 3. In the chat, type @ followed by the MCP server name and your instructions, e.g., "@FreeAgent MCP Server list my timeslips from this week" That's it! The server will respond to your query, and you can continue using it as needed. Here is a step-by-step guide with screenshots.

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: MCP Claude Code

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

FreeAgent MCP Server

FreeAgent MCP Server

Features

Prerequisites

Installation

Option 1: Direct Node.js Installation

Option 2: Docker Installation

Configuration

For Node.js Installation:

For Docker Installation:

Usage

List Timeslips

Create Timeslip

Timer Controls

Development

Node.js Development

Docker Development

Contributing

License

Acknowledgments

Resources

Tools

Latest Blog Posts

MCP directory API