Mudah MCP Server

MCP Server Documentation

Connect AI assistants to Timemoz via the Model Context Protocol (MCP). Query projects, tasks, time tracking, reports, and calendar events — without leaving the chat interface.

Streamable HTTPOAuth 2.0 / PATRead-only

Overview

Mudah MCP is a Model Context Protocol (MCP) server that connects AI assistants to Timemoz — a time tracking platform for teams. It exposes read-only tools for querying projects, tasks, time tracking entries, reports, and calendar events, enabling AI assistants to surface productivity insights and generate reports without leaving the chat interface.

Transport: Streamable HTTP
Authentication: OAuth 2.0 (Authorization Code + PKCE) or Personal Access Token (PAT)
All tools are read-only — no data is created, modified, or deleted

Authentication

Two Ways to Authenticate

Option 1 — OAuth 2.0

Recommended

Authorization Code flow with PKCE. The OAuth metadata discovery endpoint follows RFC 8414.

Endpoint	URL
OAuth Metadata	`/.well-known/oauth-authorization-server`
Authorization	`/mcp-api/oauth/authorize`
Token	`/mcp-api/oauth/token`
Registration	`/mcp-api/oauth/register`
Revocation	`/mcp-api/oauth/revoke`

After completing the OAuth flow, include the token in every request:

Authorization: Bearer mcp_oauth_<token>

Option 2 — Personal Access Token

Generate a PAT from your Timemoz account settings and include it in the request header. Suitable for personal scripts and integrations where the full OAuth flow is not required.

Add this to your request header:

Authorization: Bearer mcp_pat_<token>

Tip: Treat PATs like passwords. Revoke any token you suspect has been exposed from Timemoz → Settings → Tokens.

MCP Endpoint

POST /mcp

The server accepts MCP messages via HTTP POST. All tools follow the MCP Specification.

Tools

Available Tools

Every tool exposed by the Mudah MCP server. All read-only.

get_me

Get information about the currently authenticated user.

Parameters: none

Returns: User name, username, role, and company.

list_projects

List all projects in the company with optional filtering.

Parameter	Type	Required	Description
`search`	`string`	No	Filter by project name
`status`	`active \| archived`	No	Project status (default: active)
`clientUuid`	`string`	No	Filter by client UUID
`page`	`number`	No	Page number (default: 1)
`perPage`	`number`	No	Items per page, max 100 (default: 20)

Returns: Paginated list of projects.

get_project_detail

Get full details of a single project.

Parameter	Type	Required	Description
`uuid`	`string`	Yes	Project UUID

Returns: Budget, member list, task count, and client info.

get_tracking_summary

Get a summary of tracked hours within a date range, grouped by day, user, project, or task.

Parameter	Type	Required	Description
`dateFrom`	`string`	Yes	Start date (YYYY-MM-DD)
`dateTo`	`string`	Yes	End date (YYYY-MM-DD), max range 366 days
`projectUuid`	`string`	No	Filter by project
`userUuid`	`string`	No	User UUID; omit for current user, pass "all" for entire team
`groupBy`	`user \| project \| task \| day`	No	Group results by (default: day)

Returns: Aggregated hours broken down by the selected group dimension.

get_recent_trackings

Get the latest time tracking entries with project and task details.

Parameter	Type	Required	Description
`limit`	`number`	No	Number of entries, max 100 (default: 20)
`userUuid`	`string`	No	User UUID (default: current user; MANAGER+ can view others)

Returns: Recent time entries with associated project and task context.

list_tasks

List tasks across projects with optional filtering. Includes tasks synced from Jira and ClickUp integrations.

Parameter	Type	Required	Description
`projectUuid`	`string`	No	Filter by project
`assigneeUuid`	`string`	No	Filter by assignee
`status`	`string`	No	Task status: open, in_progress, done, etc.
`keyword`	`string`	No	Search by task name
`page`	`number`	No	Page number (default: 1)
`perPage`	`number`	No	Items per page, max 100 (default: 20)

Returns: Paginated list of tasks.

get_project_report

Get a full report for a single project including total hours, contributors, budget usage, and breakdown by user, task, and day.

Parameter	Type	Required	Description
`uuid`	`string`	Yes	Project UUID
`dateFrom`	`string`	No	Start date (YYYY-MM-DD), default: 30 days ago
`dateTo`	`string`	No	End date (YYYY-MM-DD), default: today

Returns: Comprehensive project report with time and budget analysis.

get_team_report

Get a team productivity report with total hours, projects, and per-member breakdown.

Role required: MANAGER or above.

Parameter	Type	Required	Description
`dateFrom`	`string`	Yes	Start date (YYYY-MM-DD)
`dateTo`	`string`	Yes	End date (YYYY-MM-DD)
`userUuids`	`string[]`	No	Filter by specific user UUIDs

Returns: Team-wide productivity metrics and per-member breakdown.

list_calendar_events

List Google Calendar events within a date range. Events are sourced from synced Google Calendar data.

Parameter	Type	Required	Description
`startDate`	`string`	Yes	Start date (ISO 8601, e.g. 2026-05-01T00:00:00Z)
`endDate`	`string`	Yes	End date (ISO 8601, e.g. 2026-05-31T23:59:59Z)
`source`	`company \| personal \| all`	No	Event source filter (default: all)
`skip`	`number`	No	Pagination offset (default: 0)
`take`	`number`	No	Number of events, max 100 (default: 20)

Returns: Calendar events with title, time, and source information.

Example Prompts

Try Asking Your AI Assistant

Once connected, you can ask your AI assistant things like:

"How many hours did I track this week?"

"Show me all active projects."

"Generate a report for project Alpha for last month."

"What tasks are currently in progress for the backend project?"

"Give me a team productivity summary for Q1 2026."

"What company events are scheduled this week?"

Health Check

GET /healthz

Returns the following payload when the server is running:

{ "ok": true, "service": "mudah-mcp", "timestamp": "..." }

Tool Behavior Notes

How every Mudah MCP tool behaves by default.

Read-only

All tools are read-only (readOnlyHint: true, destructiveHint: false).

Idempotent

Calling them multiple times returns the same result for the same inputs.

Company-scoped

Data is scoped to the authenticated user's company — cross-company access is not supported.

Role-based access

get_team_report requires MANAGER+; get_recent_trackings can view other users only at MANAGER+.

Ready to Connect Your AI?

Generate a Personal Access Token in your Timemoz settings or start the OAuth flow, then point your MCP-compatible AI assistant at our endpoint.

Get Help Connecting MCP Privacy Policy