README.md•13.1 kB
# 📊 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
```bash
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
<details>
<summary><strong>Claude Desktop</strong></summary>
Add to your Claude Desktop claude_desktop_config.json file:
**MacOS:** `~/Library/Application Support/Claude/claude_desktop_config.json`
**Windows:** `%APPDATA%\Claude\claude_desktop_config.json`
```json
{
"mcpServers": {
"moco": {
"command": "npx",
"args": ["-y", "@niondigital/moco-mcp"],
"env": {
"MOCO_API_KEY": "your-moco-api-key",
"MOCO_SUBDOMAIN": "your-subdomain"
}
}
}
}
```
</details>
<details>
<summary><strong>Cursor</strong></summary>
Add to your Cursor settings:
**MacOS:** `~/Library/Application Support/Cursor/User/settings.json`
**Windows:** `%APPDATA%\Cursor\User\settings.json`
**Linux:** `~/.config/Cursor/User/settings.json`
```json
{
"mcpServers": {
"moco": {
"command": "npx",
"args": ["-y", "@niondigital/moco-mcp"],
"env": {
"MOCO_API_KEY": "your-moco-api-key",
"MOCO_SUBDOMAIN": "your-subdomain"
}
}
}
}
```
</details>
<details>
<summary><strong>Windsurf</strong></summary>
Add to your Windsurf MCP configuration:
```json
{
"mcpServers": {
"moco": {
"command": "npx",
"args": ["-y", "@niondigital/moco-mcp"],
"env": {
"MOCO_API_KEY": "your-moco-api-key",
"MOCO_SUBDOMAIN": "your-subdomain"
}
}
}
}
```
</details>
<details>
<summary><strong>Claude Code (CLI)</strong></summary>
Add the MCP server to Claude Code:
```bash
claude mcp add -e MOCO_API_KEY="your-moco-api-key" -e MOCO_SUBDOMAIN="your-subdomain" moco -- npx -y @niondigital/moco-mcp
```
</details>
<details>
<summary><strong>Gemini CLI</strong></summary>
Configure Gemini CLI with MCP support:
```json
{
"mcpServers": {
"moco": {
"command": "npx",
"args": ["-y", "@niondigital/moco-mcp"],
"env": {
"MOCO_API_KEY": "your-moco-api-key",
"MOCO_SUBDOMAIN": "your-subdomain"
}
}
}
}
```
</details>
<details>
<summary><strong>Kiro</strong></summary>
1. Go to `Kiro` > `MCP Servers`
2. Add new MCP server by clicking `+ Add`
3. Paste the configuration below:
```json
{
"mcpServers": {
"moco": {
"command": "npx",
"args": [
"-y",
"@niondigital/moco-mcp"
],
"env": {
"MOCO_API_KEY": "your-moco-api-key",
"MOCO_SUBDOMAIN": "your-subdomain"
},
"disabled": false,
"autoApprove": []
}
}
}
```
4. Click `Save` to apply changes
</details>
<details>
<summary><strong>LM Studio</strong></summary>
1. Go to `Program` (right side) > `Install` > `Edit mcp.json`
2. Paste the configuration below:
```json
{
"mcpServers": {
"moco": {
"command": "npx",
"args": ["-y", "@niondigital/moco-mcp"],
"env": {
"MOCO_API_KEY": "your-moco-api-key",
"MOCO_SUBDOMAIN": "your-subdomain"
}
}
}
}
```
3. Click `Save` to apply changes
4. Toggle MCP server on/off from the right hand side (under `Program`) or by clicking the plug icon at the bottom of the chat box
</details>
## 🔑 MOCO API Setup
### Getting Your API Credentials
1. **Log into your MOCO account**
2. **Navigate to API settings:**
- Go to **Profile** → **Integrations**
- Or visit: `https://niondigital.mocoapp.com/profile/integrations`
3. **Copy the listed API key**
4. **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**
```bash
export MOCO_API_KEY="your-moco-api-key"
export MOCO_SUBDOMAIN="your-subdomain"
```
**Option 2: .env File (for local development)**
```env
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:**
```json
{
"name": "weekly_time_report",
"arguments": {
"week_start": "2024-01-15",
"include_billable_analysis": true
}
}
```
**Vacation Planning:**
```json
{
"name": "vacation_planning_assistant",
"arguments": {
"planned_start_date": "2024-07-15",
"planned_end_date": "2024-07-29"
}
}
```
**Work-Life Balance Analysis:**
```json
{
"name": "smart_work_life_balance_advisor",
"arguments": {
"analysis_weeks": 6,
"target_hours_per_week": 40
}
}
```
**Compliance Check:**
```json
{
"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:**
```json
{
"name": "get_activities",
"arguments": {
"startDate": "2024-01-01",
"endDate": "2024-01-31"
}
}
```
**Filter activities for a specific project:**
```json
{
"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:**
```json
{
"name": "get_user_projects",
"arguments": {}
}
```
**Search projects:**
```json
{
"name": "get_user_projects",
"arguments": {
"query": "website"
}
}
```
### Get User Project Tasks
```json
{
"name": "get_user_project_tasks",
"arguments": {
"projectId": 123456
}
}
```
### Get User Holidays
```json
{
"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
```json
{
"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
```json
{
"name": "get_user_sick_days",
"arguments": {
"year": 2024
}
}
```
### Get Public Holidays
```json
{
"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
<details>
<summary><strong>Local Development</strong></summary>
If you want to run from source:
```bash
git clone https://github.com/niondigital/moco-mcp.git
cd moco-mcp
npm install
npm run build
npm start
```
Then configure your MCP client to use the local path:
```json
{
"mcpServers": {
"moco": {
"command": "node",
"args": ["/path/to/moco-mcp/dist/index.js"],
"env": {
"MOCO_API_KEY": "your-moco-api-key",
"MOCO_SUBDOMAIN": "your-subdomain"
}
}
}
}
```
</details>
<details>
<summary><strong>Docker Support</strong></summary>
```dockerfile
FROM node:18-alpine
WORKDIR /app
RUN npm install -g @niondigital/moco-mcp
ENV MOCO_API_KEY=""
ENV MOCO_SUBDOMAIN=""
CMD ["@niondigital/moco-mcp"]
```
</details>
## 🔍 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:
```bash
NODE_ENV=development npx -y @niondigital/moco-mcp
```
### Testing Connection
You can test the server manually:
```bash
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
1. Fork the repository
2. Create a feature branch: `git checkout -b feature-name`
3. Make your changes and add tests
4. Run tests: `npm test`
5. Submit a pull request
## 📄 License
MIT License - see [LICENSE](LICENSE) file for details.
## 🆘 Support
- **MOCO API Issues:** [MOCO API Documentation](https://github.com/hundertzehn/mocoapp-api-docs)
- **MCP Protocol:** [MCP Documentation](https://modelcontextprotocol.io/)
- **This Package:** [GitHub Issues](https://github.com/niondigital/moco-mcp/issues)