Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type @ followed by the MCP server name and your instructions, e.g., "@timescribe-mcp how many hours did I track per project last week?"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
An MCP server that gives Claude read-only access to your local TimeScribe time tracking data. Ask things like "how many hours did I track per project last week?" without exporting a CSV.
Reads TimeScribe's local SQLite database directly, read-only. It never writes.
Works while TimeScribe is running, including the live timer.
No network access. Your data stays on your machine.
TimeScribe installed (macOS or Windows)
Node.js 22.13 or newer
Related MCP server: RescueTime MCP Server
git clone https://github.com/bverhoeve/timescribe-mcp && cd timescribe-mcp
npm ci && npm run build
claude mcp add timescribe -- node "$(pwd)/dist/index.js"Add to claude_desktop_config.json:
{
"mcpServers": {
"timescribe": { "command": "node", "args": ["/absolute/path/to/timescribe-mcp/dist/index.js"] }
}
}Found automatically:
macOS: ~/Library/Application Support/timescribe/database/database.sqlite
Windows: %APPDATA%\timescribe\database\database.sqlite (unverified; if it isn't found, set TIMESCRIBE_DB_PATH)
Elsewhere, set TIMESCRIBE_DB_PATH to the full path of database.sqlite.
Tool | What it returns |
| All projects, including archived ones ( |
| Work, break and scheduled hours for a date range, grouped per |
| Individual work/break entries in a range, filterable by |
Dates are YYYY-MM-DD, inclusive, in the timezone set in TimeScribe. Leave out from and to for the current week (Monday to Sunday). Output times are ISO 8601 with offset.
An entry counts on the day it started (TimeScribe splits entries at midnight itself).
A running timer counts up to now. A timer left open while TimeScribe was closed counts up to the last moment the app saw it running.
work_hours is tracked time only. TimeScribe's own balance also credits public holidays and absences as worked hours, so in weeks with a holiday this server reports less than the app's balance.
scheduled_hours comes from your TimeScribe work schedule and does not deduct holidays or absences.
npm test # type-check, build, run all tests (never touches your real data)
npm run inspect # open the MCP Inspector against your real databaseMIT
Total tracked work and break hours in TimeScribe for a date range (default: current ISO week, Monday to Sunday), split per project, per day, or per project per day. Entries count on the day they started. work_hours is tracked time only: unlike the TimeScribe app it does not credit public holidays or absences. scheduled_hours is the planned hours from the work schedule, without deducting holidays or absences. Entries without a project appear with project_id null. Also reports the currently running timer.
| Name | Required | Description | Default |
|---|---|---|---|
| to | No | End date, inclusive (YYYY-MM-DD). Pass with `from`, or omit both for the current ISO week. | |
| from | No | Start date, inclusive (YYYY-MM-DD). Pass with `to`, or omit both for the current ISO week. | |
| group_by | No | How to split the totals: per project (default), per day, or per project per day |
| Name | Required | Description |
|---|---|---|
| range | Yes | |
| groups | Yes | |
| totals | Yes | |
| running_timer | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With readOnlyHint=true and openWorldHint=false already covering the safety profile, the description adds genuinely useful behavioral context: entries count on their start day, work_hours excludes holiday/absence credit unlike the app, scheduled_hours does not deduct absences, and the currently running timer is reported. It does not mention pagination or result size, which for a summarised report is a minor gap.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The purpose and default range are front-loaded in the first sentence, and each subsequent sentence adds a distinct caveat about how the numbers are computed. It is dense for a three-parameter tool but nearly every clause carries information an agent would otherwise guess wrong.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a read-only aggregation tool with an output schema and full schema coverage, the definition supplies the defaults, the counting rule, the null-project case, and the exclusion caveats. Nothing required to call it correctly or interpret the totals is missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the schema already documents from, to, and group_by fully, establishing the baseline of 3. The description restates the grouping options and the date default but adds no syntax or format detail beyond what the schema provides for the parameters themselves.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb and resource ('Total tracked work and break hours in TimeScribe for a date range') and enumerates the three grouping dimensions, so an agent knows exactly what is aggregated. It is clearly distinguishable from the raw-entry siblings list_entries and list_projects, and it even defines the calculation semantics of the returned figures.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Gives clear context: the date range defaults to the current ISO week (Monday to Sunday), and from/to are passed together. However, it never explicitly routes the agent away from list_entries or list_projects when raw data is wanted, so usage is inferred rather than stated.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List individual TimeScribe time entries (work and break intervals) that started in a date range, oldest first. Use for detail behind a total; use get_time_summary for totals. Defaults to the current ISO week. Returns at most 500 entries; truncated=true means narrow the range.
| Name | Required | Description | Default |
|---|---|---|---|
| to | No | End date, inclusive (YYYY-MM-DD). Pass with `from`, or omit both for the current ISO week. | |
| from | No | Start date, inclusive (YYYY-MM-DD). Pass with `to`, or omit both for the current ISO week. | |
| type | No | Only work or only break entries; default both | |
| project_id | No | Only entries for this project id (see list_projects) |
| Name | Required | Description |
|---|---|---|
| range | Yes | |
| entries | Yes | |
| truncated | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations declare readOnlyHint=true and openWorldHint=false, so safety is covered structurally. The description adds genuinely new behavioral context: result ordering (oldest first), a hard cap ('at most 500 entries'), and the meaning of the truncated flag with remediation ('narrow the range'). It stops short of describing rate limits or error behavior, so 4 rather than 5.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Three sentences, no filler. The purpose and scope lead, the sibling comparison follows, and the truncation caveat is last where it matters for recovery. Every sentence earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
An output schema exists, so return-value structure needn't be explained, and the description correctly focuses on what the schema cannot convey: default range, result ordering, the 500-entry cap, and the truncated signal. Nothing needed to call this correctly is missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, and each parameter (from, to, type, project_id) is documented in the schema itself, including the default-ISO-week pairing rule and the pointer to list_projects. The description only restates the range default, so the schema carries the load — baseline 3.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb and resource ('List individual TimeScribe time entries'), scopes it ('work and break intervals that started in a date range'), and even specifies ordering ('oldest first'). It explicitly contrasts with the sibling get_time_summary, so an agent can discriminate without opening either schema.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Gives an explicit routing rule: 'Use for detail behind a total; use get_time_summary for totals.' It also states the default behavior when no range is supplied ('Defaults to the current ISO week'), leaving no inference required.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List all TimeScribe projects, including archived (deleted) ones, which old entries may still reference. Use the ids to filter list_entries.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
| Name | Required | Description |
|---|---|---|
| projects | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and openWorldHint=false, so the safety profile is covered. The description adds real behavioral value by disclosing that archived/deleted projects are returned and that stale entries may still reference them — information not available in the structured fields.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two tight sentences with zero filler. The scope caveat (archived included) is front-loaded and the actionable guidance follows immediately.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
An output schema exists, so return structure need not be described. The description covers scope, the archived-project nuance, and the intended downstream use — everything an agent needs to call this no-parameter tool correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool takes zero parameters, so there is nothing to document and the baseline of 4 applies. The description correctly implies the operation is unfiltered (it lists all projects).
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb and resource ('List all TimeScribe projects') and adds a non-obvious scope detail: archived/deleted projects are included. It does not explicitly distinguish itself from list_entries or get_time_summary, but the resource is distinct enough that confusion is unlikely.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Gives clear downstream guidance: 'Use the ids to filter list_entries,' which tells the agent when this tool is the right first step in a workflow. It stops short of naming when-not-to-use conditions or an alternative project-listing route.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
v0.1.0get_time_summarylist_entrieslist_projectsScored across 3 tools
Each tool targets a distinct level of the domain: projects, individual entries, and aggregated summaries. The descriptions explicitly disambiguate by telling the agent when to use list_entries vs get_time_summary, eliminating overlap.
All three names follow a clean snake_case verb_noun pattern (list_projects, list_entries, get_time_summary), with list_* for collections and get_* for a computed value used predictably.
Three tools is at the low end but each earns its place and maps to a genuinely different question (what projects exist, what happened in detail, what the totals are). A read-only analytics surface this tight is defensible, though it leaves little room for growth.
The set covers the read/analysis lifecycle well but is entirely read-only: there is no way to create, edit, or delete entries, manage projects, or start/stop the running timer that get_time_summary reports. Notable gaps if the agent is expected to do more than report on time data.
Connects AI assistants to TrackingTime for querying time entries, projects, tasks, customers, and team data using natural language.
Track billable time from your AI chat: timers, entries, reports, CSV export. All data stays local.
Track billable time from your AI chat: timers, entries, reports, CSV export. All data stays local.
Track billable time from your AI chat: timers, entries, reports, CSV export. All data stays local.
