QSS GPS MCP

QSS GPS MCP

Add GPS goals and log time directly from Claude. No timesheets to open, no commands to run.

---

Install (employees do this once)

Open Claude Desktop → Settings → Developer → Edit Config and paste:

{
  "mcpServers": {
    "qss-gps": {
      "command": "uvx",
      "args": [
        "--from",
        "git+https://github.com/YOUR_ORG/qss-gps-mcp",
        "qss-gps-mcp"
      ]
    }
  }
}

Save the file and restart Claude Desktop. That's it — Claude Desktop downloads and runs the MCP automatically.

---

First-time login (once per ~30 days)

The first time you use any GPS tool, Claude will tell you to connect first. Ask Claude:

"Connect my GPS account"

A browser window will open on your desktop showing the GPS login page. Log in with your GPS credentials. Once you see the dashboard, the window closes and you're connected. Claude will confirm.

The session lasts ~30 days. Claude will remind you when it expires.

---

Daily use — adding tasks

Just tell Claude what you did:

"Add a task to Zscaler today: Fixed the Jenkins pipeline timeout issue. 3 hours."

"Log 1 hour for Aroris yesterday — daily standup call."

"Add to AveriSource on June 24: Sprint planning and backlog grooming. 2 hours."

Claude creates the goal in GPS and logs the time automatically. A browser window may appear briefly — that's normal.

---

Bulk backfill — filling a whole month

"Fill Aroris goals for July 2026 — daily standup only, 1 hour per day."

"Fill Zscaler for July 1–22 using my task log at ~/projects/zscaler/.claude/task-log/tasks.md — 8 hours per day."

Claude will:

1. Show you a preview of every day
2. Ask you to confirm
3. Insert goals (canary date first, then the rest)
4. Log time against each goal (canary first, then the rest)

---

Available tools

| Tool | What it does | |------|-------------| | save_gps_session | Opens GPS login window — run once per ~30 days | | add_task | Add one task — creates goal + logs time | | preview_goals | Preview a date range without submitting anything | | create_goals | Create GPS goals (dry_run=True by default) | | log_time | Log time against goals (dry_run=True by default) |

---

Task log format (for bulk backfill from a file)

### 2026-07-01 — Fixed login timeout bug
**Done:** Found the JWT TTL was set to 15 min, changed to 8h. Deployed to staging.
---

### 2026-07-02 — Jenkins pipeline upgrade
**Done:** Upgraded Jenkins from 2.401 to 2.440, resolved plugin conflicts.
---

---

Session storage

The GPS session is saved to ~/.config/qss-gps/storage_state.json on your machine. Delete this file to force a fresh login.

Idempotency files (so re-runs skip already-done dates) are also in ~/.config/qss-gps/.

---

Requirements

• Claude Desktop (macOS or Windows)
• uv — installed automatically with Claude Desktop on macOS, or install from astral.sh/uv
• No Python install needed. No server to host. No commands to run.