EverHour MCP Server

A Model Context Protocol (MCP) server for EverHour time tracking and project management integration. This server enables AI assistants to interact with EverHour's API for comprehensive time tracking, project management, task management, expense tracking, and reporting capabilities.

Features

🕐 Time Tracking

• Timer Management: Start, stop, and monitor active timers
• Time Records: Create, update, delete, and list time entries
• Time Reporting: Generate detailed time reports by project, user, or date range

📋 Project Management

• Project CRUD: Create, read, update, and delete projects
• Project Structure: Manage sections, labels, and project organization
• Budget Tracking: Set and monitor project budgets (time and money)
• Billing Configuration: Configure hourly rates and billing types

✅ Task Management

• Task Operations: Full CRUD operations for tasks
• Task Organization: Assign tasks to projects, sections, and users
• Task Estimates: Set and track time estimates
• Task Status: Manage open/closed status and progress

👥 User & Team Management

• User Profiles: Access user information and permissions
• Team Organization: Create and manage teams
• Role Management: Handle admin, supervisor, and member roles

💰 Client & Expense Management

• Client Management: Create and manage client information
• Expense Tracking: Record and categorize business expenses
• Invoice Integration: Prepare data for invoicing workflows

📊 Reporting & Analytics

• Time Summaries: Generate comprehensive time tracking reports
• Project Reports: Detailed project performance analytics
• User Reports: Individual productivity and time allocation reports
• Custom Filtering: Filter reports by date, project, user, or task

Installation

1. Clone and navigate to the directory:

   git clone <repository-url>
   cd mcp-everhour
   

2. Install dependencies:

   npm install
   

3. Get your EverHour API Key:

   • Go to EverHour Settings
   • Navigate to Settings → API
   • Generate a new API key
   • Copy the API key for configuration

4. Validate your API key (optional but recommended):

   npm run auth "your_api_key_here"
   

Configuration

Environment Variables

Create a .env file in the project root:

# EverHour Configuration
EVERHOUR_API_KEY=your_everhour_api_key_here

# Server Configuration (optional)
PORT=6791

Alternative Configuration

You can also provide the API key during MCP initialization rather than using environment variables.

Usage

Development Mode

Start the EverHour MCP server in development mode:

npm run dev

The server will run on http://localhost:6791/mcp/everhour/

Production Mode

1. Build the project:

   npm run build
   

2. Start the server:

   npm run start
   

Testing the Server

Test the server and verify available tools:

# Start the server in one terminal
npm run dev

# Test the server in another terminal
npm run test:server

MCP Client Configuration

Add the EverHour MCP server to your MCP client configuration:

{
  "mcpServers": {
    "everhour": {
      "command": "npx",
      "args": ["ts-node", "src/index.ts"],
      "cwd": "/path/to/mcp-everhour",
      "env": {
        "EVERHOUR_API_KEY": "your_api_key_here"
      }
    }
  }
}

Available Tools (38 total)

Authentication

• set_api_key - Set the EverHour API key for authentication

User Management

• get_me - Get current user profile information
• list_users - List all users in the workspace
• get_user - Get specific user details by ID

Project Management

• list_projects - List all projects with filtering options
• get_project - Get specific project details
• create_project - Create a new project
• update_project - Update existing project
• delete_project - Delete a project

Task Management

• list_tasks - List tasks with comprehensive filtering
• get_task - Get specific task details
• create_task - Create a new task
• update_task - Update existing task
• delete_task - Delete a task

Time Tracking

• list_time_records - List time records with date and project filters
• get_time_record - Get specific time record details
• create_time_record - Create a new time entry
• update_time_record - Update existing time record
• delete_time_record - Delete a time record

Timer Management

• get_running_timer - Get currently running timer
• start_timer - Start a timer for a specific task
• stop_timer - Stop the currently running timer

Client Management

• list_clients - List all clients
• get_client - Get specific client details
• create_client - Create a new client
• update_client - Update existing client
• delete_client - Delete a client

Expense Management

• list_expenses - List expenses with filtering
• create_expense - Create a new expense record

Reporting & Analytics

• get_project_report - Get detailed project time report
• get_user_report - Get detailed user time report
• get_time_summary - Get time tracking summary with grouping

Project Structure

• list_sections - List sections for a project
• create_section - Create a new section in a project
• list_labels - List labels for projects
• create_label - Create a new label

Team Management

• list_teams - List all teams in the workspace
• create_team - Create a new team

Example Usage

Testing the Server

Use the test script to verify the server is working:

npm run test:server

This will:

• Perform a health check
• Initialize with your API key
• List all available tools
• Test some basic API calls

Start a Timer

{
  "tool": "start_timer",
  "arguments": {
    "task": "task_id_here",
    "comment": "Working on feature implementation"
  }
}

Create a Time Record

{
  "tool": "create_time_record",
  "arguments": {
    "task": "task_id_here",
    "time": 7200,
    "date": "2024-01-15",
    "comment": "Code review and testing"
  }
}

List Projects

{
  "tool": "list_projects",
  "arguments": {
    "status": "active",
    "limit": 50
  }
}

Create a Project

{
  "tool": "create_project",
  "arguments": {
    "name": "Website Redesign",
    "client": "client_id_here",
    "type": "board",
    "billing": {
      "type": "project_hourly",
      "rate": 75
    },
    "budget": {
      "type": "time",
      "budget": 144000
    }
  }
}

API Reference

Authentication

The EverHour MCP server uses API key authentication. The API key can be provided in two ways:

1. Environment Variable: Set EVERHOUR_API_KEY in your environment
2. MCP Initialization: Provide api_key parameter during MCP initialization

Error Handling

The server provides detailed error messages and codes:

• AUTH_ERROR - Authentication failed or API key not provided
• INVALID_PARAMS - Required parameters missing or invalid
• HTTP_XXX - HTTP status code errors from EverHour API
• NETWORK_ERROR - Network connectivity issues

Rate Limiting

The server respects EverHour's API rate limits. If you encounter rate limiting, the server will return appropriate error messages.

Troubleshooting

Common Issues

1. Authentication Errors

   • Verify your API key is correct
   • Check that the API key has sufficient permissions
   • Ensure you're using a valid, active API key

2. Network Errors

   • Check your internet connection
   • Verify EverHour's service status
   • Check for firewall or proxy issues

3. Permission Errors

   • Ensure your API key has the necessary permissions
   • Contact your EverHour administrator for access rights

Debugging

Enable debug logging by setting the DEBUG environment variable:

DEBUG=everhour:* npm run dev

Testing API Key

Use the auth helper to validate your API key:

npm run auth "your_api_key_here"

This will test your API key and display available permissions and accessible data.

Available NPM Scripts

• npm run dev - Start the server in development mode
• npm run build - Build the TypeScript project
• npm run start - Start the built server
• npm run auth "api_key" - Test and validate your API key
• npm run test:server - Test the running server and list tools

Contributing

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Add tests if applicable
5. Submit a pull request

License

MIT License. See LICENSE file for details.

Support

For issues and questions:

1. Check the EverHour API Documentation
2. Review the troubleshooting section above
3. Open an issue in this repository

Changelog

v1.0.0

• Initial release with comprehensive EverHour API coverage
• Full CRUD operations for projects, tasks, time records
• Timer management and time tracking
• Expense tracking and client management
• Reporting and analytics tools
• Team and user management features