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

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: BigTime MCP Server

Endpoints (deployed)

• POST /mcp — the MCP endpoint (bearer token required).

• GET /health — returns {"status":"ok"} (no auth).

Environment variables

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 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.