What is Freeagent Mcp

Freeagent-mcp is a Claude MCP server designed to manage FreeAgent timeslips and timers, allowing users to track time and handle timeslip operations seamlessly.

Use cases

Use cases include tracking billable hours for clients, managing project timelines, and automating timeslip entries for freelancers and agencies.

How to use

To use freeagent-mcp, clone the repository, install dependencies, and set up OAuth credentials. You can run it directly with Node.js or use Docker for containerized deployment.

Key features

Key features include listing and filtering timeslips, creating and updating timeslips, starting and stopping timers, deleting timeslips, automatic OAuth token refresh, comprehensive error handling, and Docker support.

Where to use

Freeagent-mcp is primarily used in project management, time tracking, and accounting fields where FreeAgent is utilized for managing financial records and timesheets.

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

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

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