Freeagent

🚀 FreeAgent MCP Service

A Claude MCP (Model Context Protocol) server for managing FreeAgent time entries and timers. This server enables Claude to interact with your FreeAgent account to track time, manage timers, and handle time entry operations.

✨ Features

• List and filter time entries with nested data
• Create new time entries
• Update existing time entries
• Start and stop timers
• Delete time entries
• Automatically refresh access tokens
• Comprehensive error handling
• Docker support

📦 Prerequisites

• Node.js 18+ (for direct Node.js usage)
• Docker and 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. Obtain your OAuth tokens:

# Set your FreeAgent credentials
export FREEAGENT_CLIENT_ID="your_client_id"
export FREEAGENT_CLIENT_SECRET="your_client_secret"

# Access token
curl -X POST "https://oauth2api.freeagent.com/v1/oauth/token" \
     -u "$FREEAGENT_CLIENT_ID:$FREEAGENT_CLIENT_SECRET" \
     -d "grant_type=client_credentials&scope=full Accounting"

Option 2: Installation with Docker

1. Clone the repository:

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

2. Build the Docker image:

docker build -t freeagent-mcp .

3. Run the container:

docker run -p 3000:3000 --env-file .env freeagent-mcp

📚 Configuration

Environment Variables

Create a .env file and add the following content:

FREEAGENT_CLIENT_ID=your_client_id
FREEAGENT_CLIENT_SECRET=your_client_secret
PORT=3000

Docker Environment Variables

Configure environment variables in docker-compose.yml:

version: '3'
services:
  freeagent-mcp:
    image: freeagent-mcp
    ports:
      - "3000:3000"
    environment:
      - FREEAGENT_CLIENT_ID=your_client_id
      - FREEAGENT_CLIENT_SECRET=your_client_secret

💻 Usage Examples

Listing Time Entries

curl http://localhost:3000/api/timeslips

Creating a Time Entry

curl -X POST "http://localhost:3000/api/timeslips" \
     -H "Content-Type: application/json" \
     -d '{"description":"Project meeting","duration":60}'

Updating a Time Entry

curl -X PUT "http://localhost:3000/api/timeslips/123" \
     -H "Content-Type: application/json" \
     -d '{"description":"Detailed project plan","duration":90}'

Deleting a Time Entry

curl -X DELETE "http://localhost:3000/api/timeslips/123"

Controlling Timers

Starting a Timer

curl -X POST "http://localhost:3000/api/timers/123/start"

Stopping a Timer

curl -X POST "http://localhost:3000/api/timers/123/stop"

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