@mhdd_24/worksnaps-mcp

MCP server for Worksnaps time tracking from Cursor chat. Verify your API token, list projects and tasks, and log offline time without opening the Worksnaps web UI.

Same architecture as Timelog / Flyway / Notepad++ / Caffeine / Workspace Build MCP packages.

Full documentation: docs/WIKI.md

---

How it works (30 seconds)

You (chat)
  → worksnaps-mcp
  → Worksnaps REST API (XML over HTTPS)
  → GET /me.xml | /projects.xml | /tasks.xml
  → POST /projects/{id}/time_entries.xml (offline time)

1. Configure WORKSNAPS_API_TOKEN (Profile & Settings → Web Service API in Worksnaps)
2. Say "list Worksnaps projects" to pick a project ID
3. Say "list tasks for project 1234" to pick a task ID
4. Say "log 480 minutes to Worksnaps project 1234 task 56" with an optional comment

---

Prerequisites

Requirement	Notes
Node.js 18+	Uses native fetch
Worksnaps API token	Profile & Settings → Web Service API → Show my API Token
Project + task IDs	Use list_projects / list_tasks, or set defaults in env

---

Install

Option A — npm (after publish)

npm install -g @mhdd_24/worksnaps-mcp

Option B — npx

npx @mhdd_24/worksnaps-mcp

Option C — clone and build

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

---

Configure Cursor

Edit ~/.cursor/mcp.json:

{
  "mcpServers": {
    "worksnaps": {
      "command": "npx",
      "args": ["-y", "@mhdd_24/worksnaps-mcp"],
      "env": {
        "WORKSNAPS_API_TOKEN": "<your-api-token>",
        "WORKSNAPS_DEFAULT_PROJECT_ID": "1234",
        "WORKSNAPS_DEFAULT_TASK_ID": "5678"
      }
    }
  }
}

Local development:

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

Reload MCP after saving.

---

Tools

Tool	Purpose
whoami	Resolve current user from API token (GET /me.xml)
list_projects	List accessible projects
list_tasks	List tasks in a project
log_time	Create offline time entry for yourself

Chat examples

• "Run whoami on Worksnaps"
• "List Worksnaps projects"
• "List tasks for Worksnaps project 3456"
• "Log 6 hours offline time to Worksnaps project 3456 task 12 — comment: Sprint development"

---

Environment variables

Variable	Required	Purpose
WORKSNAPS_API_TOKEN	Yes*	API token (Basic auth username; password ignored)
WORKSNAPS_DEFAULT_PROJECT_ID	No	Default project for log_time
WORKSNAPS_DEFAULT_TASK_ID	No	Default task for log_time
WORKSNAPS_BASE_URL	No	API base URL (default https://api.worksnaps.com/api)

*Can be passed as token per tool call instead.

---

Notes

• log_time creates offline time entries (Worksnaps API: POST /projects/{project_id}/time_entries.xml).
• from_timestamp is aligned to a 10-minute boundary (Worksnaps API requirement).
• Default startHour is 9 (local time) when only a date is provided.

---

License

ISC