niondigital/moco-mcp

6 stars 6 forks Quality 66 Trend 14MIT

A Model Context Protocol (MCP) server that provides employee read access to the MOCO API for time tracking, project management, holiday tracking, and presence monitoring.

Overview

A Model Context Protocol (MCP) server that provides employee read access to the MOCO API for time tracking, project management, holiday tracking, and presence monitoring. That's it! The server will start and be ready to connect to your MCP client. - Node.js ≥ 18.0.0 - MOCO account with API access - MOCO API key and subdomain Add to your Claude Desktop claude_desktop_config.json file: ~/Library/Application Support/Claude/claude_desktop_config.json %APPDATA%\Claude\claude_desktop_config.json ~/Library/Application Support/Cursor/User/settings.json %APPDATA%\Cursor\User\settings.json ~/.config/Cursor/User/settings.json 1. Go to Kiro > MCP Servers 2. Add new MCP server by clicking + Add 3. Paste the configuration below: 1. Go to Program (right side) > Install > Edit mcp.json 2. Paste the configuration below:

README

📊 MOCO MCP Server

A Model Context Protocol (MCP) server that provides employee read access to the MOCO API for time tracking, project management, holiday tracking, and presence monitoring.

⚡ Quick Start

npx -y @niondigital/moco-mcp

That’s it! The server will start and be ready to connect to your MCP client.

🚀 Installation

Prerequisites

Node.js ≥ 18.0.0
MOCO account with API access
MOCO API key and subdomain

MCP Client Integration

🔑 MOCO API Setup

Getting Your API Credentials

Log into your MOCO account
Navigate to API settings:
- Go to Profile → Integrations
- Or visit: https://niondigital.mocoapp.com/profile/integrations
Copy the listed API key
Note your subdomain:
- From your MOCO URL: https://yourcompany.mocoapp.com
- Your subdomain is: yourcompany

Environment Variables

You can set environment variables in several ways:

Option 1: System Environment Variables

export MOCO_API_KEY="your-moco-api-key"
export MOCO_SUBDOMAIN="your-subdomain"

Option 2: .env File (for local development)

MOCO_API_KEY=your-moco-api-key
MOCO_SUBDOMAIN=your-subdomain

Option 3: MCP Client Configuration (recommended) Use the env section in your MCP client configuration as shown above.

🛠️ Available Tools

Tool	Description	Parameters
`get_activities`	Get activities within a date range with summation and optional project filtering	`startDate`, `endDate` (ISO 8601), `projectId` (optional)
`get_user_projects`	List all assigned projects or search by query	`query` (optional)
`get_user_project_tasks`	Get all tasks for a specific assigned project	`projectId`
`get_user_holidays`	Get holiday overview for a year with calculations	`year`
`get_user_presences`	Get presence data within a date range with daily summaries	`startDate`, `endDate` (ISO 8601)
`get_user_sick_days`	Get sick days overview for a year with calculations	`year`
`get_public_holidays`	Get public holidays for a year with working days calculations	`year`

🎯 Available Prompts

The MoCo MCP server provides 8 intelligent prompts that orchestrate multiple tools to deliver comprehensive insights:

Prompt	Description	Key Parameters
`weekly_time_report`	Generates detailed weekly time tracking report with project breakdown	`week_start`, `include_billable_analysis`
`vacation_planning_assistant`	Assists with vacation planning by analyzing available days and holidays	`planned_start_date`, `planned_end_date`
`personal_productivity_insights`	Analyzes work habits and provides productivity recommendations	`analysis_period`, `focus_area`
`monthly_business_review`	Creates comprehensive business reports with trends and metrics	`month`, `year`, `include_comparisons`
`smart_work_life_balance_advisor`	Evaluates work-life balance with personalized recommendations	`analysis_weeks`, `target_hours_per_week`
`project_time_analysis`	Detailed project time analysis with efficiency metrics	`project_ids`, `time_period`
`team_capacity_overview`	Team capacity planning with absence and resource analysis	`planning_horizon`, `include_holidays`
`work_hours_compliance_check`	Compliance check for working time regulations	`check_period`, `max_weekly_hours`, `max_daily_hours`

Prompt Examples

Weekly Time Report:

{
  "name": "weekly_time_report",
  "arguments": {
    "week_start": "2024-01-15",
    "include_billable_analysis": true
  }
}

Vacation Planning:

{
  "name": "vacation_planning_assistant",
  "arguments": {
    "planned_start_date": "2024-07-15",
    "planned_end_date": "2024-07-29"
  }
}

Work-Life Balance Analysis:

{
  "name": "smart_work_life_balance_advisor",
  "arguments": {
    "analysis_weeks": 6,
    "target_hours_per_week": 40
  }
}

Compliance Check:

{
  "name": "work_hours_compliance_check",
  "arguments": {
    "check_period": "last_month",
    "max_weekly_hours": 48,
    "max_daily_hours": 10
  }
}

📝 Tool Examples

Get Activities

Filter all activities in a date range:

{
  "name": "get_activities",
  "arguments": {
    "startDate": "2024-01-01",
    "endDate": "2024-01-31"
  }
}

Filter activities for a specific project:

{
  "name": "get_activities",
  "arguments": {
    "startDate": "2024-01-01",
    "endDate": "2024-01-31",
    "projectId": 123456
  }
}

Sample Output:

Activities from 2024-01-01 to 2024-01-31:

2024-01-15:
  Project 123 (Website Redesign):
    Task 456 (Frontend Development): 4.5h (4:30)
    Task 789 (Backend API): 3.25h (3:15)
    Project total: 7.75h (7:45)
  Daily total: 7.75h (7:45)

Grand total: 7.75h (7:45)

Get User Projects

List all assigned projects:

{
  "name": "get_user_projects",
  "arguments": {}
}

Search projects:

{
  "name": "get_user_projects",
  "arguments": {
    "query": "website"
  }
}

Get User Project Tasks

{
  "name": "get_user_project_tasks",
  "arguments": {
    "projectId": 123456
  }
}

Get User Holidays

{
  "name": "get_user_holidays",
  "arguments": {
    "year": 2024
  }
}

Sample Output:

Holiday overview for 2024:

Taken holiday days:
- 2024-03-15: 1.0 day
- 2024-04-22: 0.5 day
- 2024-07-08: 1.0 day

Summary:
- Taken vacation: 2.5 days
- Annual entitlement: 25 days
- Utilization: 10% (2.5/25)
- Remaining vacation: 22.5 days

Get User Presences

{
  "name": "get_user_presences",
  "arguments": {
    "startDate": "2024-01-01",
    "endDate": "2024-01-07"
  }
}

Sample Output:

Presences from 2024-01-01 to 2024-01-07:

Daily presences:
- 2024-01-01: 8.25h (8:15)
- 2024-01-02: 7.5h (7:30)
- 2024-01-03: 8.0h (8:00)

Grand total: 23.75h (23:45)

Statistics:
- Working days: 3
- Average per day: 7.92h (7:55)

Get User Sick Days

{
  "name": "get_user_sick_days",
  "arguments": {
    "year": 2024
  }
}

Get Public Holidays

{
  "name": "get_public_holidays",
  "arguments": {
    "year": 2024
  }
}

Sample Output:

Public holidays for 2024:

Holiday dates:
- 2024-01-01: New Year's Day
- 2024-04-01: Good Friday
- 2024-04-03: Easter Monday
- 2024-05-01: Labor Day
- 2024-05-09: Ascension Day
- 2024-05-20: Whit Monday
- 2024-10-03: German Unity Day
- 2024-12-25: Christmas Day
- 2024-12-26: Boxing Day

Summary:
- Total public holidays: 9 days
- Approximate working days: 251 days

🔧 Advanced Configuration

🔍 Troubleshooting

Common Issues

❌ Authentication Error:

API authentication failed. Please check MOCO_API_KEY.

Verify your API key is correct and has necessary permissions
Check if the API key is properly set in environment variables
Ensure the key hasn’t expired

❌ Subdomain Error:

MOCO_SUBDOMAIN should only contain the subdomain name

Use only the subdomain part: company (not company.mocoapp.com)
Remove https:// and .mocoapp.com from the subdomain

❌ Node.js Version Error:

This package requires Node.js >= 18.0.0

Update Node.js to version 18 or higher
Check your version: node --version

❌ npx Connection Issues:

Error: Cannot find module '@niondigital/moco-mcp'

Ensure you have internet connection
Try: npx --yes @niondigital/moco-mcp
Clear npx cache: npx clear-npx-cache

❌ MCP Client Not Finding Tools:

Restart your MCP client after configuration changes
Check that environment variables are properly set
Verify JSON configuration syntax is correct

Debug Mode

For debugging, you can run the server with additional logging:

NODE_ENV=development npx -y @niondigital/moco-mcp

Testing Connection

You can test the server manually:

echo '{"jsonrpc": "2.0", "id": 1, "method": "tools/list"}' | npx -y @niondigital/moco-mcp

🌟 Features

✅ Read-only Access: Safe API integration with no data modification
🔄 Automatic Pagination: Handles large datasets seamlessly
📊 Smart Aggregation: Automatic summation by date, project, and task
🎯 Project Filtering: Filter activities by specific projects
🧩 Comprehensive Tools: 7 specialized tools for different use cases
🎯 Intelligent Prompts: 8 AI-powered prompts for complex analysis and insights
🌐 Multi-Client Support: Works with all major MCP clients

🤝 Contributing

Fork the repository
Create a feature branch: git checkout -b feature-name
Make your changes and add tests
Run tests: npm test
Submit a pull request

📄 License

MIT License - see LICENSE file for details.

🆘 Support

MOCO API Issues: MOCO API Documentation
MCP Protocol: MCP Documentation
This Package: GitHub Issues

View the full README on GitHub

Install

npx -y @niondigital/moco-mcp

New to MCP? Start with the mcpskill.org guide →

Configuration

{
  "mcpServers": {
    "moco": {
      "command": "npx",
      "args": ["-y", "@niondigital/moco-mcp"],
      "env": {
        "MOCO_API_KEY": "your-moco-api-key",
        "MOCO_SUBDOMAIN": "your-subdomain"
      }
    }
  }
}