@mhdd_24/timelog-mcp

MCP server that logs time to Azure DevOps work items through the TimeLog API. Use it from Cursor, Claude Desktop, VS Code Copilot, or any MCP-compatible client.

You type natural language — the assistant calls log_time for you. No manual USER_ID / USER_NAME / USER_EMAIL setup; your Azure DevOps PAT resolves identity automatically.

Full documentation: docs/WIKI.md · GitHub Wiki

How it works (30 seconds)

You (chat) → MCP client → timelog-mcp → Azure DevOps connectionData (PAT)
                                      → TimeLog API (function key)
                                      → Time entry on work item

1. PAT calls connectionData → returns userId, userName, userEmail, instanceId
2. TimeLog URL is built from instanceId — not hardcoded
3. Time types come from GET /api/{instanceId}/timetype/project — not a fixed enum
4. log_time validates the type, POSTs the entry, returns the log ID

Prerequisites

| Requirement | Notes | |-------------|--------| | Node.js 18+ | Uses native fetch | | Azure DevOps PAT | Read access to your org (for connectionData) | | TimeLog function key | TIMELOG_FUNCTIONS_KEY — from your team / Azure Functions | | Project GUID (optional) | Default PROJECT_ID so you don't pass it every time |

Install

Option A — npm (recommended after publish)

npm install -g @mhdd_24/timelog-mcp

This installs the timelog-mcp CLI and compiles dist/ via the package prepack script.

Option B — npx (no global install)

npx @mhdd_24/timelog-mcp

Downloads and runs the latest published version on each invocation.

Option C — clone and build (contributors)

git clone https://github.com/Mhdd-24/Timelog-MCP.git
cd Timelog-MCP
npm install
npm run build
node dist/index.js

Configure your MCP client

Cursor

Edit Cursor Settings → MCP or ~/.cursor/mcp.json:

{
  "mcpServers": {
    "timelog": {
      "command": "npx",
      "args": ["-y", "@mhdd_24/timelog-mcp"],
      "env": {
        "AZURE_DEVOPS_ORG": "YourOrg",
        "AZURE_DEVOPS_PAT": "<your-azure-devops-pat>",
        "TIMELOG_FUNCTIONS_KEY": "<your-function-key>",
        "PROJECT_ID": "<optional-default-project-guid>"
      }
    }
  }
}

After global install, you can use:

"command": "timelog-mcp"

Local development:

"command": "node",
"args": ["C:/path/to/timelog-mcp/dist/index.js"]

Restart Cursor (or toggle the MCP server off/on) after saving.

Claude Desktop

%APPDATA%\Claude\claude_desktop_config.json (Windows) or ~/Library/Application Support/Claude/claude_desktop_config.json (macOS):

{
  "mcpServers": {
    "timelog": {
      "command": "npx",
      "args": ["-y", "@mhdd_24/timelog-mcp"],
      "env": {
        "AZURE_DEVOPS_ORG": "YourOrg",
        "AZURE_DEVOPS_PAT": "<your-pat>",
        "TIMELOG_FUNCTIONS_KEY": "<your-function-key>",
        "PROJECT_ID": "<optional-project-guid>"
      }
    }
  }
}

Environment variables

| Variable | Required | Default | Purpose | |----------|----------|---------|---------| | AZURE_DEVOPS_PAT | Yes* | — | PAT for connectionData | | AZURE_DEVOPS_ORG | No | RTSCargo | Azure DevOps organization | | TIMELOG_FUNCTIONS_KEY | Yes | — | Sent as X-Functions-Key header | | PROJECT_ID | No | — | Default project GUID for log_time | | TIMELOG_BASE_URL | No | https://boznet-timelogapi.azurewebsites.net | TimeLog API host |

* Or pass pat on each tool call.

Aliases: ADO_PAT, ADO_ORG, FUNCTION_KEY, projectId, etc. (see WIKI).

Never commit PAT or function keys. Put them only in MCP env or a local .env (for npm run dev).

Tools

| Tool | Purpose | |------|---------| | whoami | Test PAT — shows userId, name, email, instanceId | | list_time_types | Lists valid categories from the TimeLog API | | log_time | Log time to a work item |

Usage

Step 1 — Verify setup (optional)

In chat:

Run whoami on the timelog MCP.

Expected: your ADO identity and instanceId.

Step 2 — See valid time types (optional)

list_time_types

Examples: Development, Documentation, Sprint Planning Calls, Bug Fixing, …

Step 3 — Log time

Log 120 minutes of Development to work item 85352, comment: Implemented feature X.

Log 9 hours 45 minutes to 85344 — type Development, comment: Loader for read operation.

log_time parameters

| Parameter | Required | Example | |-----------|----------|---------| | minutes | Yes | 585 (9h 45m) | | timeTypeDescription | Yes | "Development" | | workItemId | Yes | 85352 | | projectId | No* | Project GUID | | comment | No | Free text | | date | No | 2026-07-03 (defaults to today) | | pat | No | Only if not in env |

* Optional when PROJECT_ID is set in MCP config.

Minutes cheat sheet

| Duration | minutes | |----------|-----------| | 30 min | 30 | | 1 hour | 60 | | 2 hours | 120 | | 8 hours | 480 | | 9h 45m | 585 |

What happens after npm install?

1. Package files land in node_modules/@mhdd_24/timelog-mcp/ (or global prefix if -g).
2. prepack / publish includes compiled dist/ — no local build needed for end users.
3. The timelog-mcp bin points to dist/index.js.
4. Your MCP client runs that entry over stdio (stdin/stdout = MCP protocol; logs go to stderr).
5. On startup: validateEnv() checks TIMELOG_FUNCTIONS_KEY; warns if PAT is missing.
6. Tools are registered; the server waits for CallTool requests from the AI.

After publishing to npm (maintainers)

1. Bump version in package.json and src/config/timelog.config.ts (TL.SERVER.VERSION).
2. Build and test: npm run build then test with local mcp.json.
3. Publish: npm publish --access public (logged in as package owner).
4. Users update by restarting MCP — npx picks up the new version automatically.
5. Global install users: npm update -g @mhdd_24/timelog-mcp.

See WIKI — Publishing for the full checklist.

Troubleshooting

| Problem | Fix | |---------|-----| | MCP server won't start | Set TIMELOG_FUNCTIONS_KEY in MCP env | | No PAT provided | Set AZURE_DEVOPS_PAT or pass pat on the tool | | Invalid time type | Run list_time_types; use an exact match (case-insensitive) | | projectId is required | Set PROJECT_ID in env or pass projectId on log_time | | Stale version after publish | Restart MCP; npx uses latest unless pinned |

More detail: docs/WIKI.md § Troubleshooting.

License

ISC