@everhour/mcp-server

Complete Everhour API integration for Model Context Protocol (MCP) with 100% endpoint coverage

A comprehensive MCP server that provides seamless integration with the Everhour API, enabling AI assistants like Claude to manage time tracking, projects, tasks, and team productivity workflows.

🚀 Quick Start

Installation

# Using npx (recommended)
npx @everhour/mcp-server

# Or install globally
npm install -g @everhour/mcp-server
everhour-mcp-server

Prerequisites

• Node.js 18+
• Everhour account with paid plan (API access required)
• Everhour API key (get it from Everhour Settings → My Profile)

Configuration

Set your Everhour API key as an environment variable:

export EVERHOUR_API_KEY=\"your_api_key_here\"

📋 MCP Client Setup

Claude Desktop

Add to your Claude Desktop configuration:

{
  \"mcpServers\": {
    \"everhour\": {
      \"command\": \"npx\",
      \"args\": [\"@everhour/mcp-server\"],
      \"env\": {
        \"EVERHOUR_API_KEY\": \"your_api_key_here\"
      }
    }
  }
}

Other MCP Clients

For other MCP-compatible clients, use:

# Command
npx @everhour/mcp-server

# Environment Variables
EVERHOUR_API_KEY=your_api_key_here

✨ Features

🎯 100% API Coverage

All 37 available Everhour API endpoints implemented as MCP tools

🛠 Complete Functionality

• Project Management: Create, update, list, and delete projects
• Task Management: Full CRUD operations with estimates and time logging
• Time Tracking: Comprehensive time record management
• Timer Control: Start, stop, and monitor active timers
• Client Management: Manage clients and business details
• Section Organization: Project section management
• Team Collaboration: User and team member management

🔧 Developer-Friendly

• TypeScript: Full type safety and IntelliSense support
• Input Validation: Comprehensive validation with detailed error messages
• Human-Readable: Time formats like "2h 30m" alongside seconds
• Error Handling: Graceful error handling with helpful messages

🔧 Available Tools (37 total)

• everhour_list_projects - List all projects with filtering options
• everhour_get_project - Get details of a specific project
• everhour_create_project - Create a new project
• everhour_update_project - Update project details
• everhour_delete_project - Delete a project

Core Task Management:

• everhour_list_tasks - List tasks with filtering by project, status, assignee
• everhour_get_task - Get details of a specific task
• everhour_create_task - Create a new task
• everhour_update_task - Update task details
• everhour_delete_task - Delete a task

Extended Task Features:

• everhour_get_tasks_for_project - Get all tasks for specific project
• everhour_update_task_estimate - Update task estimate
• everhour_delete_task_estimate - Delete task estimate
• everhour_add_time_to_task - Add time directly to task
• everhour_update_task_time - Update task time
• everhour_delete_task_time - Delete time from task

• everhour_list_time_records - List time records with date/project filtering
• everhour_get_time_record - Get details of a specific time record
• everhour_create_time_record - Log time (supports human-readable formats)
• everhour_update_time_record - Update existing time records
• everhour_delete_time_record - Delete a time record

Core Timer Functions:

• everhour_get_current_timer - Get the currently running timer
• everhour_start_timer - Start a new timer
• everhour_stop_timer - Stop the current timer
• everhour_list_timers - List timer history
• everhour_timer_status - Get timer status summary

Extended Timer Features:

• everhour_get_running_timer - Get running timer (alternative endpoint)
• everhour_start_timer_for_task - Start timer directly for specific task

• everhour_list_clients - List all clients
• everhour_get_client - Get details of a specific client
• everhour_create_client - Create a new client
• everhour_update_client - Update client details
• everhour_delete_client - Delete a client

• everhour_list_all_sections - List all sections (global search)
• everhour_get_section - Get details of a specific section
• everhour_create_section - Create a new section
• everhour_update_section - Update section details
• everhour_delete_section - Delete a section

• everhour_get_current_user - Get current user profile
• everhour_list_team_users - List all team users
• everhour_get_user - Get details of a specific team user

📚 Examples

Starting a Timer

{
  \"tool\": \"everhour_start_timer_for_task\",
  \"arguments\": {
    \"taskId\": \"task_123\",
    \"comment\": \"Working on user authentication feature\"
  }
}

Logging Time

{
  \"tool\": \"everhour_create_time_record\",
  \"arguments\": {
    \"time\": \"2h 30m\",
    \"date\": \"2024-01-15\",
    \"task\": \"task_123\",
    \"comment\": \"Implemented login functionality and wrote tests\"
  }
}

Creating a Project

{
  \"tool\": \"everhour_create_project\",
  \"arguments\": {
    \"name\": \"Mobile App Development\",
    \"client\": 456,
    \"type\": \"board\",
    \"billing\": {
      \"type\": \"hourly_rate\",
      \"rate\": 85.00
    }
  }
}

Getting Project Tasks

{
  \"tool\": \"everhour_get_tasks_for_project\",
  \"arguments\": {
    \"projectId\": \"proj_789\",
    \"status\": \"open\"
  }
}

🕐 Time Format Support

The server supports flexible time input formats:

• Human-readable: \"2h 30m\", \"90m\", \"1h 30m 45s\"
• Minutes only: \"90m\" (90 minutes)
• Seconds: 3600 (1 hour in seconds)

🔧 Environment Variables

| Variable | Required | Default | Description | |----------|----------|---------|-------------| | EVERHOUR_API_KEY | ✅ Yes | - | Your Everhour API key | | EVERHOUR_API_BASE_URL | ❌ No | https://api.everhour.com | API base URL | | EVERHOUR_READONLY_MODE | ❌ No | false | Enable readonly mode for safety |

🔒 Readonly Mode

Readonly mode provides an additional security layer by blocking all write and delete operations, allowing only safe read operations.

When to Use Readonly Mode

• Production environments where data integrity is critical
• Reporting and analytics use cases
• Shared or untrusted environments
• Testing and development with live data
• Compliance requirements for read-only access

Enabling Readonly Mode

# Via environment variable
EVERHOUR_READONLY_MODE=true npx @everhour/mcp-server

# Or export for session
export EVERHOUR_READONLY_MODE=true
npx @everhour/mcp-server

Claude Desktop Readonly Configuration

{
  "mcpServers": {
    "everhour-readonly": {
      "command": "npx",
      "args": ["@everhour/mcp-server"],
      "env": {
        "EVERHOUR_API_KEY": "your_api_key_here",
        "EVERHOUR_READONLY_MODE": "true"
      }
    }
  }
}

What's Blocked in Readonly Mode

• ❌ Creating: Projects, tasks, clients, sections, time records
• ❌ Updating: Any modifications to existing data
• ❌ Deleting: Removal of any resources
• ❌ Timer Control: Starting/stopping timers
• ❌ Time Logging: Adding or modifying time entries

What's Allowed in Readonly Mode

• ✅ Listing: All list operations (everhour_list_*)
• ✅ Reading: All get operations (everhour_get_*)
• ✅ Status Checks: Timer status, user information
• ✅ Searching: Project, task, and client searches
• ✅ Reports: Time record queries and analytics

Readonly Mode Status

When the server starts, it will log the current mode:

🔒 EVERHOUR MCP SERVER - READONLY MODE ACTIVE
   Available tools: 19/37
   Blocked tools: 18 (write/delete operations)
   To enable full mode: Set EVERHOUR_READONLY_MODE=false

Or in full mode:

🔓 EVERHOUR MCP SERVER - FULL MODE ACTIVE
   All 37 tools available
   To enable readonly mode: Set EVERHOUR_READONLY_MODE=true

📖 Documentation

• API Coverage Report - Complete endpoint mapping
• Examples Guide - Comprehensive usage examples
• Official Everhour API - Official API documentation

🛠 Development

Local Development

# Clone repository
git clone https://github.com/yourusername/everhour-mcp-server.git
cd everhour-mcp-server

# Install dependencies
npm install

# Set environment variables
cp .env.example .env
# Edit .env with your API key

# Development mode
npm run dev

# Build
npm run build

# Run built version
npm start

Project Structure

src/
├── api/
│   └── everhour-client.ts    # Everhour API client
├── tools/
│   ├── clients.ts            # Client management tools
│   ├── projects.ts           # Project management tools
│   ├── tasks.ts              # Task management tools
│   ├── task-extensions.ts    # Extended task features
│   ├── time-records.ts       # Time record tools
│   ├── timers.ts             # Timer control tools
│   ├── sections.ts           # Section management tools
│   └── users.ts              # User management tools
├── types/
│   └── everhour.ts           # TypeScript type definitions
└── index.ts                  # MCP server entry point

Scripts

• npm run dev - Development mode with auto-reload
• npm run build - Build TypeScript to JavaScript
• npm start - Start the built server
• npm run lint - Run ESLint
• npm run lint:fix - Fix ESLint issues
• npm run clean - Clean build directory

🤝 Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

1. Fork the repository
2. Create your feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m '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.

🔗 Links

• npm Package
• GitHub Repository
• Everhour Official Site
• Model Context Protocol

📞 Support

• Issues: GitHub Issues
• Everhour API: Official Documentation
• MCP Protocol: MCP Documentation

🏆 Features

• ✅ Complete API Coverage - All 37 Everhour endpoints
• ✅ Type Safety - Full TypeScript implementation
• ✅ Input Validation - Comprehensive validation with Zod
• ✅ Error Handling - Graceful error handling
• ✅ Human-Readable - Time formats and clear responses
• ✅ Well-Documented - Extensive documentation and examples
• ✅ Production-Ready - Robust and reliable implementation

Made with ❤️ for the Model Context Protocol community