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 at POST 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
timely_employer_info	POST /v3/employer-info	Company name lookup by 7-digit register
timely_overview_attd	POST /v3/overview-attd	Company-wide attendance report (paginated)
timely_employee_attd	POST /v3/employee-attd	One employee's attendance between two dates
timely_employee_info	POST /v3/employee-info	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.

Endpoints (deployed)

• POST /mcp — the MCP endpoint (bearer token required).
• GET /health — returns {"status":"ok"} (no auth).

Environment variables

Variable	Required	Notes
TIMELY_USERNAME	yes (for API calls)	Timely API login
TIMELY_PASSWORD	yes (for API calls)	Timely API password
TIMELY_MCP_AUTH_TOKEN	yes (remote)	Secret clients send as Bearer. The POST endpoint fails closed without it. Generate: openssl rand -hex 32
TIMELY_COMPANY_REGISTER	no	Default 7-digit register
TIMELY_BASE_URL	no	Defaults to https://api.timely.mn

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

{
  "mcpServers": {
    "timely-remote": {
      "type": "http",
      "url": "https://timely-mcp.vercel.app/mcp",
      "headers": { "Authorization": "Bearer <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 no vercel.json and no /api directory by design. Adding either reintroduced routing/entrypoint bugs.
• Every push to main auto-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 than token/access_token/accessToken/jwt, add it to extractToken() in src/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.