stefanskiasan/everhour-mcp-server

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

📚 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

🔒 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

• - Complete endpoint mapping
• - 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 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