intervals-mcp
A standalone MCP server, CLI, and Claude Code plugin for local-first Intervalstime tracking. Starting a timer or logging a time entry hits a local SQLitedatabase first; entries sync to Intervals in the background or on demand.Reports and queries are always local-only and never call the Intervals API.
Install (Claude Code plugin)
/plugin marketplace add sixfeetup/intervals-mcp
/plugin install intervals@intervals-mcp
There is no build step to run: the dist/ bundle is committed to the repo.The only requirement is Node >= 22.5.
Install (any MCP host)
Clone the repo and point your MCP host at the bundled server:
git clone https://github.com/sixfeetup/intervals-mcp.git
{
"command": "node",
"args": ["/path/to/intervals-mcp/dist/server.mjs"]
}
Configuration
Credentials and settings are resolved in this order:
- Environment variables
config.jsoninsideINTERVALS_HOME(or~/.intervals/)
Environment variables
| Variable | Description |
|---|---|
INTERVALS_API_KEY |
Intervals API key for HTTP Basic auth |
INTERVALS_BASE_URL |
Intervals API base URL (default: https://api.myintervals.com/) |
INTERVALS_PERSON_ID |
Your Intervals person ID (required for time-entry sync) |
INTERVALS_HOME |
Override the default local storage path (~/.intervals/) |
config.json keys
If you prefer file-based configuration, create config.json inside INTERVALS_HOME (or ~/.intervals/):
| Key | Type | Description |
|---|---|---|
apiKey |
string |
Intervals API key for HTTP Basic auth |
baseUrl |
string |
Intervals API base URL (default: https://api.myintervals.com/) |
personId |
number |
Your Intervals person ID (required for time-entry sync) |
syncIntervalMs |
number |
Background sync interval in milliseconds |
Running intervals setup (or the /intervals-setup slash command) writesthis file with 0600 permissions and never puts the API key in modelcontext — the key is entered at an interactive, hidden prompt in your ownterminal.
CLI
The bundle ships a zero-dependency CLI (dist/cli.mjs, exposed as intervalsvia package.json#bin when installed as a package):
| Command | Description |
|---|---|
setup |
Configure credentials and run initial project sync |
status |
Show DB path, credential source, timers, pending sync |
sync-projects |
Refresh the local project catalog |
sync-now |
Push pending time entries to Intervals now |
timers [recent] / timers edit <timer_id> [field=value ...] / timers delete <timer_id> |
Show, edit, or delete timers |
time [range] / time edit <id> [field=value ...] |
Report time entries (today, yesterday, this-week, last-week, this-month, last-month, YYYY-MM-DD, YYYY-MM-DD..YYYY-MM-DD), or edit one (stop_time=HH:mm recalculates duration) |
project-defaults <project_id> <worktype_id> [module_id] |
Set project defaults |
Run node dist/cli.mjs help (or intervals help) for the full usage text.
Agent tools
When installed as a Claude Code plugin, tools surface with the mcp__plugin_intervals_intervals__ prefix:
| Tool | Description |
|---|---|
mcp__plugin_intervals_intervals__find_project_context |
Search the local project catalog for IDs and classifications (local-only) |
mcp__plugin_intervals_intervals__start_timer |
Start a local timer with a simple description and optional start_at; project/worktype/module are optional |
mcp__plugin_intervals_intervals__stop_timer |
Stop a timer, resolve classification, create a pending time entry, and sync |
mcp__plugin_intervals_intervals__edit_timer |
Update description or project/worktype/module hints on a running local timer |
mcp__plugin_intervals_intervals__delete_timer |
Safely delete an active timer or stopped timer with no linked time entry |
mcp__plugin_intervals_intervals__add_time |
Add a completed time entry directly (duration in minutes) |
mcp__plugin_intervals_intervals__edit_time |
Edit an existing local time entry by short ID or linked timer ID; use stop_time for local stop-time changes that recalculate duration |
mcp__plugin_intervals_intervals__delete_time |
Delete a local or synced time entry by short ID or linked timer ID |
mcp__plugin_intervals_intervals__query_time |
Report time entries by date range and project filter (local-only) |
mcp__plugin_intervals_intervals__list_timers |
List active or recent local timers |
mcp__plugin_intervals_intervals__lookup_time_entry |
Map a stopped local timer ID to the linked local time entry ID |
mcp__plugin_intervals_intervals__list_time |
List recent local time entries with sync status |
mcp__plugin_intervals_intervals__set_project_defaults |
Configure default worktype/module for a project |
mcp__plugin_intervals_intervals__sync_now |
Immediately retry syncing pending time entries to Intervals |
mcp__plugin_intervals_intervals__start_timer accepts optional start_at values for retroactivelocal timer starts. Use HH:mm or H:mm for today in local time,YYYY-MM-DD HH:mm for a local date/time, or an ISO datetime with an explicitoffset/timezone. Future start_at values are rejected.
Slash commands
| Command | Description |
|---|---|
/intervals-setup |
Configure Intervals credentials and run the initial project sync |
/intervals-status |
Show Intervals DB path, credential source, active timers, pending sync, last project sync |
/intervals-sync-projects |
Refresh the local Intervals catalog of clients, projects, worktypes, and modules |
/intervals-sync-now |
Push pending local time entries to Intervals now |
/intervals-timers |
Show active or recent Intervals timers, or edit/delete a timer by ID |
/intervals-time |
Report local time entries by range, or edit an entry by ID |
/intervals-project-defaults |
Set the default worktype and optional module for a project |
How it works
- Timers are local-only. Starting a timer writes a lightweight local rowwith just a description. Project, worktype, and module hints are optional.
- Running timers can be reclassified locally. Edit a timer's project,worktype, or module hints before stopping it; the updated classification isapplied when the time entry is created.
- Stop/apply creates a time entry. When you stop a timer, you provide (orresolve) the project and worktype. The server creates a pending time entryand immediately tries to sync it to Intervals.
- Time entries are local-first.
mcp__plugin_intervals_intervals__add_time,mcp__plugin_intervals_intervals__edit_time, andmcp__plugin_intervals_intervals__stop_timerall persist toSQLite before any network call. If sync fails, the entry stays local with afailedorpendingstatus and can be retried. - Catalog sync stores active rows. Project sync fetches all catalog pages,keeps active projects and active classifications, and retains clientsreferenced by active projects.
- Reports are local-only.
mcp__plugin_intervals_intervals__query_timeand/intervals-timeread fromSQLite and never call the Intervals API.
Developer note
If you open this repository itself in Claude Code, you may see the intervalsMCP server listed as failed to connect. That's expected: the repo-root.mcp.json is the plugin's own configuration, and it references${CLAUDE_PLUGIN_ROOT}, which is only set when the plugin is installedthrough /plugin install. Editing this repo's source doesn't install theplugin, so the variable is unset and the server can't start. It's safe toreject or ignore any prompt about it while working on the code.
