Timely MCP Server
The Timely MCP Server provides access to the Timely.mn v3 time-attendance API, enabling HR and attendance management functions:
timely_employer_info– Look up a registered company's name using its 7-digit register number.timely_overview_attd– Generate a paginated, company-wide attendance report for a date range, with an optional department filter, including worked days/hours, late arrivals, absences, overtime, leave, and vacation.timely_employee_attd– Retrieve an attendance report for a single employee (identified by register number and/or phone) between two dates, showing supposed vs. actual worked days and hours.timely_employee_info– Fetch an employee's full profile — name, register number, phone, salary, and bank details — identified by register number, TIN, and/or phone.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@Timely MCP Server What's the company-wide attendance report for today?"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
Timely MCP Server
An MCP server that exposes the Timely.mn v3 time-attendance API as tools for Claude and any other MCP client.
Built for UBCab Holding. One self-contained file (src/index.ts) runs two ways:
Remote (Vercel) — Vercel's Node framework invokes the file's default
(req, res)handler. Live atPOST https://timely-mcp.vercel.app/mcp, protected by a bearer token.Local (stdio) — when run directly (
node dist/index.js), it speaks MCP over stdio for Claude Desktop.
Tools
Tool | Endpoint | Purpose |
|
| Company name lookup by 7-digit register |
|
| Company-wide attendance report (paginated) |
|
| One employee's attendance between two dates |
|
| One employee's profile (name, salary, bank) |
Login (POST /v3/login → JWT) is automatic: the token is cached and refreshed
on a 401/403. Credentials are only required when a tool actually calls the API,
so tools/list works without them.
Related MCP server: Tipsoi MCP
Endpoints (deployed)
POST /mcp— the MCP endpoint (bearer token required).GET /health— returns{"status":"ok"}(no auth).
Environment variables
Variable | Required | Notes |
| yes (for API calls) | Timely API login |
| yes (for API calls) | Timely API password |
| yes (remote) | Secret clients send as |
| no | Default 7-digit register |
| no | Defaults to |
Use locally (Claude Desktop)
npm install
npm run build{
"mcpServers": {
"timely": {
"command": "node",
"args": ["/absolute/path/to/timely-mcp/dist/index.js"],
"env": {
"TIMELY_USERNAME": "ubcabholding",
"TIMELY_PASSWORD": "your-password",
"TIMELY_COMPANY_REGISTER": "1234567"
}
}
}
}Connect to the remote endpoint
Three ways to authenticate (the endpoint accepts any of them):
1. OAuth (recommended — nothing secret in the URL). Add a custom connector
with just the URL https://timely-mcp.vercel.app/mcp. The client discovers the
OAuth metadata, opens a login page, and prompts for the access token
(TIMELY_MCP_AUTH_TOKEN). Implemented as a stateless OAuth 2.1 + PKCE server:
/.well-known/oauth-protected-resource, /.well-known/oauth-authorization-server,
/register, /authorize, /token. Auth codes and access tokens are HMAC-signed
blobs (no datastore).
2. Header (Claude Desktop JSON config).
{
"mcpServers": {
"timely-remote": {
"type": "http",
"url": "https://timely-mcp.vercel.app/mcp",
"headers": { "Authorization": "Bearer <TIMELY_MCP_AUTH_TOKEN>" }
}
}
}3. Token in URL path (for clients that can't send a header):
https://timely-mcp.vercel.app/mcp/<TIMELY_MCP_AUTH_TOKEN>
Smoke test:
curl -s -X POST https://timely-mcp.vercel.app/mcp -H 'Content-Type: application/json' -H 'Accept: application/json, text/event-stream' -H 'Authorization: Bearer <TIMELY_MCP_AUTH_TOKEN>' -d '{"jsonrpc":"2.0","id":1,"method":"tools/list","params":{}}'Deployment notes
Vercel auto-detects this repo as a Node project and runs
src/index.ts's default export as a serverless function — there is novercel.jsonand no/apidirectory by design. Adding either reintroduced routing/entrypoint bugs.Every push to
mainauto-deploys via Vercel's Git integration.Verify the JWT field with
node --env-file=.env scripts/test-login.mjs; if the token lives under a field other thantoken/access_token/accessToken/jwt, add it toextractToken()insrc/index.ts.
Security
The deployed URL + bearer token can read employee salary and bank details.
Treat both as secrets; rotate the token (openssl rand -hex 32 → update the
Vercel env var → redeploy) if it leaks.
Available Tools
4 toolstimely_employee_attdA
Attendance report for a single employee between two dates. Identify the employee by register number and/or phone. Returns supposed vs. actual worked days and hours.
Inputs: dateFrom (required), dateTo (required), company_register, register, +1 more.
timely_employee_infoA
Get a single employee's profile from Timely (name, register, phone, salary, bank details). Identify by register, tax id (tin_number), and/or phone.
Inputs: company_register, register, tin_number, phone.
timely_employer_infoA
Get organization (company) info from Timely for a given 7-digit company register. Returns the registered company name. Useful to verify a register number is valid.
Inputs: company_register.
timely_overview_attdA
Company-wide attendance report between two dates. Returns per-employee attendance detail (worked days/hours, late, absent, leave, overtime, vacation, etc.) with pagination. Set div_id to a department id, or '0' for all departments.
Inputs: dateFrom (required), dateTo (required), company_register, div_id, +2 more.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 4 tools
Each tool has a clearly distinct purpose: employee attendance, employee profile, employer info, and company-wide attendance. No overlap.
All tools follow the pattern 'timely_<entity>_<info/action>', consistently using underscores and lowercase. Minor abbreviation 'attd' instead of 'attendance' slightly reduces consistency.
With only 4 tools, the server is small but focused on core HR attendance functions. It's slightly below typical range but still appropriate for its narrow scope.
Covers essential read operations for employees, attendance, and company info, but lacks any mutation tools (create, update, delete) and other HR features like leave management.
Maintenance
Related MCP Connectors
MCP server exposing klokin time-tracking operations (employees, time entries, stores) to AI clients.
MCP server providing attendance data queries via the CloudTime API.
Connects AI assistants to TrackingTime for querying time entries, projects, tasks, customers, and team data using natural language.
Read your tracked time and projects, pause tracking or add a note, from Claude or ChatGPT.
Related MCP Servers
- AlicenseNot gradedqualityBmaintenanceMCP server for Timely time tracking API. Connects Claude Code to your Timely account for reading and creating time entries, projects, tasks, and users.9MIT
- FlicenseAqualityDmaintenanceRead-only MCP server for the Tipsoi HRM API, exposing 15 tools to read employee data, attendance, leave, overtime, and more.153-
- FlicenseAqualityDmaintenanceExposes employee leave-management operations (add employees, check balance, apply/cancel leave, view history) as MCP tools for AI clients like Claude Desktop to call directly.6-
- FlicenseNot gradedqualityCmaintenanceExposes the full public TSheets REST API v1 as MCP tools, enabling time tracking, scheduling, and PTO management operations via natural language.-