Content
# 7pace Timetracker MCP (self-hosted)
A small [Model Context Protocol](https://modelcontextprotocol.io) server that creates worklogs in **7pace Timetracker for Azure DevOps** using the [REST CRUD API](https://timehub.7pace.com/api_reference/index.html). Use it from **Cursor** or **VS Code** with GitHub Copilot MCP support.
Organization, project, tokens, and paths are **not** hardcoded: configure them in your MCP host (`env` in `mcp.json` or equivalent).
## Prerequisites
- Node.js 20+
- **7pace API token** (not an Azure DevOps PAT for 7pace calls): Timetracker → **Settings** → **Reporting and API** → create token. See [7pace API Important Information](https://support.7pace.com/hc/en-us/articles/360050677831-7pace-Timetracker-API-Important-Information).
- **Azure DevOps PAT** (optional): for work-item tools only. **User settings → Personal access tokens** with at least **Work items (Read)**. See [Use PATs](https://learn.microsoft.com/en-us/azure/devops/organizations/accounts/use-personal-access-tokens-to-authenticate).
## Install and build
```bash
cd /path/to/this-repo
npm install
npm run build
```
## Environment variables
Set these in the MCP server `env` (Cursor, VS Code, etc.). Do not commit real secrets.
| Variable | Required | Description |
|----------|----------|-------------|
| `SEVENPACE_ORG` | Yes (7pace) | Azure DevOps org name; 7pace host is `https://{SEVENPACE_ORG}.timehub.7pace.com` |
| `SEVENPACE_API_TOKEN` | Yes (7pace) | 7pace Timetracker Bearer token |
| `SEVENPACE_API_VERSION` | No | 7pace API version query param (default `3.2`) |
| `SEVENPACE_BASE_URL` | No | Override 7pace REST root (see `src/config.ts`) |
| `AZURE_DEVOPS_PAT` | Yes (ADO tools) | PAT with Work Items (Read) |
| `AZURE_DEVOPS_PROJECT` | Yes (ADO tools) | Azure DevOps **team project** name exactly as in the URL |
| `AZURE_DEVOPS_ORG` | No | ADO org for `dev.azure.com`; if unset, `SEVENPACE_ORG` is used |
| `AZURE_DEVOPS_API_VERSION` | No | REST `api-version` (default `7.1`) |
Worklog **length** is sent in **seconds** (per [7pace sample](https://github.com/7pace/timetracker-rest-api-samplecode)); this server converts **hours** to seconds (`hours × 3600`).
## Tools
- **`health`** — `GET /me` to verify 7pace token and org.
- **`list_activity_types`** — 7pace activity type names and ids.
- **`log_time`** — Structured: `workItemId`, `date` (`YYYY-MM-DD`), `hours`, `description`, optional `activityType`.
- **`log_time_natural`** — One free-text line; parses work item id, duration, date, description.
- **`list_completed_work_items`** — WIQL: assigned to you, terminal states, closed on/before a date. Optional `project` overrides `AZURE_DEVOPS_PROJECT`.
- **`list_work_items_touched_in_range`** — WIQL: assigned to you, `ChangedDate` in an inclusive date range. Optional `project` overrides `AZURE_DEVOPS_PROJECT`.
## Cursor
Example `mcp.json` shape (replace paths and use your own `env` values):
```json
{
"mcpServers": {
"7pace-timetracker": {
"command": "node",
"args": ["/absolute/path/to/repo/dist/index.js"],
"env": {
"SEVENPACE_ORG": "<your-azure-devops-org>",
"SEVENPACE_API_TOKEN": "<your-7pace-api-token>",
"AZURE_DEVOPS_PAT": "<your-ado-pat>",
"AZURE_DEVOPS_PROJECT": "<your-team-project>"
}
}
}
}
```
## VS Code (GitHub Copilot MCP)
Same `command`, `args`, and `env` as above. See [MCP configuration in VS Code](https://code.visualstudio.com/docs/copilot/reference/mcp-configuration).
Example using workspace-relative `dist` and prompted token:
```json
{
"servers": {
"7pace-timetracker": {
"type": "stdio",
"command": "node",
"args": ["${workspaceFolder}/dist/index.js"],
"env": {
"SEVENPACE_ORG": "<your-azure-devops-org>",
"SEVENPACE_API_TOKEN": "${input:sevenpaceToken}",
"AZURE_DEVOPS_PAT": "${input:adoPat}",
"AZURE_DEVOPS_PROJECT": "<your-team-project>"
}
}
},
"inputs": [
{
"id": "sevenpaceToken",
"type": "promptString",
"description": "7pace Timetracker API token",
"password": true
},
{
"id": "adoPat",
"type": "promptString",
"description": "Azure DevOps PAT (work items read)",
"password": true
}
]
}
```
Schema keys may differ by VS Code version; align with the official MCP docs.
## Run locally (stdio)
```bash
export SEVENPACE_ORG="<your-org>"
export SEVENPACE_API_TOKEN="<token>"
node dist/index.js
```
On Windows PowerShell, use `$env:SEVENPACE_ORG = "..."` instead.
## License
MIT
