FreeAgent MCP Server

by markpitt

Integrations

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

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

You must be authenticated.

A
security – no known vulnerabilities
A
license - permissive license
A
quality - confirmed to work

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.

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

  1. Features
    1. Prerequisites
      1. Installation
        1. Option 1: Direct Node.js Installation
        2. Option 2: Docker Installation
      2. Configuration
        1. For Node.js Installation:
        2. For Docker Installation:
      3. Usage
        1. List Timeslips
        2. Create Timeslip
        3. Timer Controls
      4. Development
        1. Node.js Development
        2. Docker Development
      5. Contributing
        1. License
          1. Acknowledgments

            Related MCP Servers

            • -
              security
              A
              license
              -
              quality
              An MCP server that allows accessing and managing ledger files through Claude by providing account listing, balance checking, and transaction register viewing capabilities.
              Last updated -
              1
              Python
              GPL 3.0
              • Apple
            • A
              security
              A
              license
              A
              quality
              An MCP server that enables Claude to interact with Twitter, allowing for posting tweets and searching Twitter content.
              Last updated -
              2
              65
              202
              TypeScript
              MIT License
              • Apple
            • -
              security
              F
              license
              -
              quality
              An MCP server that connects Claude for Desktop with blockchain functionality, allowing users to check balances and send tokens on EVM and Solana chains through natural language interactions.
              Last updated -
              TypeScript
              • Apple
            • -
              security
              F
              license
              -
              quality
              An MCP server that allows Claude to interact with Discord by providing tools for sending/reading messages and managing server resources through Discord's API.
              Last updated -
              JavaScript

            View all related MCP servers

            ID: 2qsl0xvx2t