{"_id":"@a-und-b/timing-mcp","_rev":"5-6186fde65314318d7d99e7c533b31017","name":"@a-und-b/timing-mcp","dist-tags":{"latest":"1.0.4"},"versions":{"1.0.0":{"name":"@a-und-b/timing-mcp","version":"1.0.0","keywords":["mcp","model-context-protocol","timing","time-tracking","project-management","api","typescript","ai","assistant","productivity"],"author":{"name":"a-und-b"},"license":"MIT","_id":"@a-und-b/timing-mcp@1.0.0","maintainers":[{"name":"a-und-b","email":"holger@andersundbesser.de"}],"homepage":"https://github.com/a-und-b/timing-mcp#readme","bugs":{"url":"https://github.com/a-und-b/timing-mcp/issues"},"bin":{"timing-mcp":"dist/index.js"},"dist":{"shasum":"4f1f44c1d923357d17b47339a677d6b2bc203dda","tarball":"https://registry.npmjs.org/@a-und-b/timing-mcp/-/timing-mcp-1.0.0.tgz","fileCount":4,"integrity":"sha512-vSh3xk0wn4iAKAaLiGctGYJxwkIAIid7OLlbpiFCMLqLCTgHYxL582kYNArKWuhJmAfbTD6y9VaGElPSmaMR8w==","signatures":[{"sig":"MEQCIACqwzEAgTuzceC1tVdqv9+734iIvI/tLVlshb8oYsmrAiAOBC5+wXY2TaRBKmV7mkyf1tUkTzcg0gf/CSA3oSbXbw==","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":56965},"main":"dist/index.js","type":"module","engines":{"node":">=18.0.0"},"gitHead":"c82d45fa5225ced64c630242a8968823242afa0f","scripts":{"dev":"tsx src/index.ts","lint":"eslint src/**/*.ts","build":"npm run clean && esbuild src/index.ts --bundle --platform=node --target=node18 --format=esm --outfile=dist/index.js --external:@modelcontextprotocol/sdk --external:timing-api-client --external:zod --external:zod-to-json-schema","clean":"rm -rf dist && mkdir -p dist","start":"node dist/index.js","typecheck":"tsc --noEmit","prepublishOnly":"npm run build"},"_npmUser":{"name":"a-und-b","email":"holger@andersundbesser.de"},"repository":{"url":"git+https://github.com/a-und-b/timing-mcp.git","type":"git"},"_npmVersion":"10.8.2","description":"Model Context Protocol (MCP) server for Timing: time tracking, project management, and productivity insights","directories":{},"_nodeVersion":"20.19.2","dependencies":{"zod":"^3.25.76","timing-api-client":"^0.1.5","zod-to-json-schema":"^3.23.5","@modelcontextprotocol/sdk":"^1.17.1"},"_hasShrinkwrap":false,"devDependencies":{"tsx":"^4.20.3","esbuild":"^0.27.1","typescript":"^5.9.2","@types/node":"^24.2.0"},"_npmOperationalInternal":{"tmp":"tmp/timing-mcp_1.0.0_1765021153091_0.6095747737802053","host":"s3://npm-registry-packages-npm-production"}},"1.0.1":{"name":"@a-und-b/timing-mcp","version":"1.0.1","keywords":["mcp","model-context-protocol","timing","time-tracking","project-management","api","typescript","ai","assistant","productivity"],"author":{"name":"a-und-b"},"license":"MIT","_id":"@a-und-b/timing-mcp@1.0.1","maintainers":[{"name":"a-und-b","email":"holger@andersundbesser.de"}],"homepage":"https://github.com/a-und-b/timing-mcp#readme","bugs":{"url":"https://github.com/a-und-b/timing-mcp/issues"},"bin":{"timing-mcp":"dist/index.js"},"dist":{"shasum":"4c6258ec1d7d0b9f2652f30c30ee7f385898e497","tarball":"https://registry.npmjs.org/@a-und-b/timing-mcp/-/timing-mcp-1.0.1.tgz","fileCount":4,"integrity":"sha512-B9vKmjWHQvVMTmFXU+iXSCWzlpfZQnNBMLt8y1jzUGFzaTXP4jhnpMr7XN9RXdEHFFCk0hCAy3EmBdc5VGwMLA==","signatures":[{"sig":"MEYCIQC2RpGSQ49CfmZbbNleh+KpVYMkQ+nL1JrWB3uLMFJagAIhANq7EBbHpEXaKf1Ejzx/V24DeSOymEgvGzx312yomxhD","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":56967},"main":"dist/index.js","type":"module","engines":{"node":">=18.0.0"},"gitHead":"c82d45fa5225ced64c630242a8968823242afa0f","scripts":{"dev":"tsx src/index.ts","lint":"eslint src/**/*.ts","build":"npm run clean && esbuild src/index.ts --bundle --platform=node --target=node18 --format=esm --outfile=dist/index.js --external:@modelcontextprotocol/sdk --external:timing-api-client --external:zod --external:zod-to-json-schema","clean":"rm -rf dist && mkdir -p dist","start":"node dist/index.js","typecheck":"tsc --noEmit","prepublishOnly":"npm run build"},"_npmUser":{"name":"a-und-b","email":"holger@andersundbesser.de"},"repository":{"url":"git+https://github.com/a-und-b/timing-mcp.git","type":"git"},"_npmVersion":"10.8.2","description":"Model Context Protocol (MCP) server for Timing: time tracking, project management, and productivity insights","directories":{},"_nodeVersion":"20.19.2","dependencies":{"zod":"^3.25.76","timing-api-client":"^0.1.5","zod-to-json-schema":"^3.23.5","@modelcontextprotocol/sdk":"^1.17.1"},"_hasShrinkwrap":false,"devDependencies":{"tsx":"^4.20.3","esbuild":"^0.27.1","typescript":"^5.9.2","@types/node":"^24.2.0"},"_npmOperationalInternal":{"tmp":"tmp/timing-mcp_1.0.1_1765021446884_0.7994825299792063","host":"s3://npm-registry-packages-npm-production"}},"1.0.2":{"name":"@a-und-b/timing-mcp","version":"1.0.2","keywords":["mcp","model-context-protocol","timing","time-tracking","project-management","api","typescript","ai","assistant","productivity"],"author":{"name":"a-und-b"},"license":"MIT","_id":"@a-und-b/timing-mcp@1.0.2","maintainers":[{"name":"a-und-b","email":"holger@andersundbesser.de"}],"homepage":"https://github.com/a-und-b/timing-mcp#readme","bugs":{"url":"https://github.com/a-und-b/timing-mcp/issues"},"bin":{"timing-mcp":"dist/index.js"},"dist":{"shasum":"46cc136bd558e40bdb1b352079efa96b05ce1e81","tarball":"https://registry.npmjs.org/@a-und-b/timing-mcp/-/timing-mcp-1.0.2.tgz","fileCount":4,"integrity":"sha512-g7+/AubEcrVKaOtl8WOo3WP9ORgvjf3UjLAOO1jW2cOEnzWtzBAL0YN8X34RqGGlqgNsETi4hhvRZkbDjZ0DlQ==","signatures":[{"sig":"MEUCIE4AM4tdhc74dn5Ml4pFNniqQsuNywWCOgJaC4P26G5/AiEAiEg+ikx9LEVkEnkpZ3cQeAP+LpefGLdchsZ2/3j7sQY=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":62567},"main":"dist/index.js","type":"module","engines":{"node":">=18.0.0"},"gitHead":"f9a42bac30dcc4f6abbb35e56df356b5d7bc8234","scripts":{"dev":"tsx src/index.ts","lint":"eslint src/**/*.ts","build":"npm run clean && esbuild src/index.ts --bundle --platform=node --target=node18 --format=esm --outfile=dist/index.js --external:@modelcontextprotocol/sdk --external:timing-api-client --external:zod --external:zod-to-json-schema","clean":"rm -rf dist && mkdir -p dist","start":"node dist/index.js","typecheck":"tsc --noEmit","prepublishOnly":"npm run build"},"_npmUser":{"name":"a-und-b","email":"holger@andersundbesser.de"},"repository":{"url":"git+https://github.com/a-und-b/timing-mcp.git","type":"git"},"_npmVersion":"10.8.2","description":"Model Context Protocol (MCP) server for Timing: time tracking, project management, and productivity insights","directories":{},"_nodeVersion":"20.19.2","dependencies":{"zod":"^3.25.76","timing-api-client":"^0.1.5","zod-to-json-schema":"^3.23.5","@modelcontextprotocol/sdk":"^1.17.1"},"_hasShrinkwrap":false,"devDependencies":{"tsx":"^4.20.3","esbuild":"^0.27.1","typescript":"^5.9.2","@types/node":"^24.2.0"},"_npmOperationalInternal":{"tmp":"tmp/timing-mcp_1.0.2_1765454209173_0.22627405731994132","host":"s3://npm-registry-packages-npm-production"}},"1.0.3":{"name":"@a-und-b/timing-mcp","version":"1.0.3","keywords":["mcp","model-context-protocol","timing","time-tracking","project-management","api","typescript","ai","assistant","productivity"],"author":{"name":"a-und-b"},"license":"MIT","_id":"@a-und-b/timing-mcp@1.0.3","maintainers":[{"name":"a-und-b","email":"holger@andersundbesser.de"}],"homepage":"https://github.com/a-und-b/timing-mcp#readme","bugs":{"url":"https://github.com/a-und-b/timing-mcp/issues"},"bin":{"timing-mcp":"dist/index.js"},"dist":{"shasum":"a216811a3d1b93ad7cf4a3fc2a8793fd92037ecd","tarball":"https://registry.npmjs.org/@a-und-b/timing-mcp/-/timing-mcp-1.0.3.tgz","fileCount":4,"integrity":"sha512-hwUJZwpncu7Kmf4b70VHtuiTpKH3e5SRMSRo8kV0DeHwHMzC8ufcCAY9HN70PtK/J26p4zFhYBSMR4zsn8zqVw==","signatures":[{"sig":"MEUCIBhwXtgZyh/UakQvC7R9nUpcjTC3+dY7/AoeLn7cNJeqAiEAm+Ihk60Tg4aea/sWytrQwtoknG4fQmtNjEuNFqToc8k=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":62583},"main":"dist/index.js","type":"module","engines":{"node":">=18.0.0"},"gitHead":"61c1b64fe1530ccdcd1a3c0508d4a86ac1e9a69c","scripts":{"dev":"tsx src/index.ts","lint":"eslint src/**/*.ts","build":"npm run clean && esbuild src/index.ts --bundle --platform=node --target=node18 --format=esm --outfile=dist/index.js --external:@modelcontextprotocol/sdk --external:timing-api-client --external:zod --external:zod-to-json-schema","clean":"rm -rf dist && mkdir -p dist","start":"node dist/index.js","typecheck":"tsc --noEmit","prepublishOnly":"npm run build"},"_npmUser":{"name":"a-und-b","email":"holger@andersundbesser.de"},"repository":{"url":"git+https://github.com/a-und-b/timing-mcp.git","type":"git"},"_npmVersion":"10.8.2","description":"Model Context Protocol (MCP) server for Timing: time tracking, project management, and productivity insights","directories":{},"_nodeVersion":"20.19.2","dependencies":{"zod":"^3.25.76","timing-api-client":"^0.1.5","zod-to-json-schema":"^3.23.5","@modelcontextprotocol/sdk":"^1.17.1"},"_hasShrinkwrap":false,"devDependencies":{"tsx":"^4.20.3","esbuild":"^0.27.1","typescript":"^5.9.2","@types/node":"^24.2.0"},"_npmOperationalInternal":{"tmp":"tmp/timing-mcp_1.0.3_1772608426868_0.6770805248299114","host":"s3://npm-registry-packages-npm-production"}},"1.0.4":{"name":"@a-und-b/timing-mcp","version":"1.0.4","description":"Model Context Protocol (MCP) server for Timing: time tracking, project management, and productivity insights","main":"dist/index.js","bin":{"timing-mcp":"dist/index.js"},"type":"module","engines":{"node":">=18.0.0"},"scripts":{"build":"npm run clean && esbuild src/index.ts --bundle --platform=node --target=node18 --format=esm --outfile=dist/index.js --external:@modelcontextprotocol/sdk --external:timing-api-client --external:zod --external:zod-to-json-schema","clean":"rm -rf dist && mkdir -p dist","typecheck":"tsc --noEmit","dev":"tsx src/index.ts","start":"node dist/index.js","prepublishOnly":"npm run build","lint":"eslint src/**/*.ts"},"keywords":["mcp","model-context-protocol","timing","time-tracking","project-management","api","typescript","ai","assistant","productivity"],"author":{"name":"a-und-b"},"license":"MIT","homepage":"https://github.com/a-und-b/timing-mcp#readme","repository":{"type":"git","url":"git+https://github.com/a-und-b/timing-mcp.git"},"bugs":{"url":"https://github.com/a-und-b/timing-mcp/issues"},"dependencies":{"@modelcontextprotocol/sdk":"^1.17.1","timing-api-client":"^0.1.5","zod":"^3.25.76","zod-to-json-schema":"^3.23.5"},"devDependencies":{"@types/node":"^24.2.0","esbuild":"^0.27.1","tsx":"^4.20.3","typescript":"^5.9.2"},"_id":"@a-und-b/timing-mcp@1.0.4","gitHead":"dbdea0579e63f97930f93e97c6a98c69167849c3","_nodeVersion":"20.19.2","_npmVersion":"10.8.2","dist":{"integrity":"sha512-AQ3XERpnFwE94yPT82nIIm89hfIQX2DvDIulS2AjD7wEY7FDuiKZ45Ly8HE1sfzu0bqWLUj0gpoV1wQBsUumsw==","shasum":"86a6a87612363f6ac3cdd91f4a86980f0670dda2","tarball":"https://registry.npmjs.org/@a-und-b/timing-mcp/-/timing-mcp-1.0.4.tgz","fileCount":4,"unpackedSize":64273,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEYCIQDWacVaG98zQ3f96FS0vYDdq7eaHfiU8SO/dIVqB6uslQIhALQ2+T1l+RuZn8AKm4zFy9wKDjkiJaS7bjDgOPWb7gpa"}]},"_npmUser":{"name":"a-und-b","email":"holger@andersundbesser.de"},"directories":{},"maintainers":[{"name":"a-und-b","email":"holger@andersundbesser.de"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/timing-mcp_1.0.4_1772610665338_0.8359788634606253"},"_hasShrinkwrap":false}},"time":{"created":"2025-12-06T11:39:13.016Z","modified":"2026-03-04T07:51:05.582Z","1.0.0":"2025-12-06T11:39:13.234Z","1.0.1":"2025-12-06T11:44:07.016Z","1.0.2":"2025-12-11T11:56:49.328Z","1.0.3":"2026-03-04T07:13:47.010Z","1.0.4":"2026-03-04T07:51:05.475Z"},"bugs":{"url":"https://github.com/a-und-b/timing-mcp/issues"},"author":{"name":"a-und-b"},"license":"MIT","homepage":"https://github.com/a-und-b/timing-mcp#readme","keywords":["mcp","model-context-protocol","timing","time-tracking","project-management","api","typescript","ai","assistant","productivity"],"repository":{"type":"git","url":"git+https://github.com/a-und-b/timing-mcp.git"},"description":"Model Context Protocol (MCP) server for Timing: time tracking, project management, and productivity insights","maintainers":[{"name":"a-und-b","email":"holger@andersundbesser.de"}],"readme":"# ⏱️ Timing MCP Server\n\nA Model Context Protocol (MCP) server that provides comprehensive access to the Timing API for time tracking, project management, and productivity insights.\n\n> [!warning]\n> This repository is not affiliated with Timing. It is an independent project created to enhance the functionality of the Timing application.\n\n> [!note]\n> This is a fork of [tomoyanakano/timing-mcp-server](https://github.com/tomoyanakano/timing-mcp-server), extended with additional capabilities, prompts support, and production-ready structure.\n\n## ⚡ Quick Start\n\n```bash\nnpx -y @a-und-b/timing-mcp\n```\n\nThat's it! The server will start and be ready to connect to your MCP client.\n\n## 🚀 Installation\n\n### Prerequisites\n\n- Node.js ≥ 18.0.0\n- Timing account with API access\n- Timing API key ([Get your API key here](https://web.timingapp.com/integrations/tokens))\n\n### MCP Client Integration\n\n<details>\n<summary><strong>Claude Desktop</strong></summary>\n\nAdd to your Claude Desktop claude_desktop_config.json file:\n\n**MacOS:** `~/Library/Application Support/Claude/claude_desktop_config.json`  \n**Windows:** `%APPDATA%\\Claude\\claude_desktop_config.json`\n\n```json\n{\n  \"mcpServers\": {\n    \"timing\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"@a-und-b/timing-mcp\"],\n      \"env\": {\n        \"TIMING_API_KEY\": \"your-timing-api-key\"\n      }\n    }\n  }\n}\n```\n\n</details>\n\n<details>\n<summary><strong>Cursor</strong></summary>\n\nAdd to your Cursor settings:\n\n**MacOS:** `~/Library/Application Support/Cursor/User/settings.json`  \n**Windows:** `%APPDATA%\\Cursor\\User\\settings.json`  \n**Linux:** `~/.config/Cursor/User/settings.json`\n\n```json\n{\n  \"mcpServers\": {\n    \"timing\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"@a-und-b/timing-mcp\"],\n      \"env\": {\n        \"TIMING_API_KEY\": \"your-timing-api-key\"\n      }\n    }\n  }\n}\n```\n\n</details>\n\n<details>\n<summary><strong>Windsurf</strong></summary>\n\nAdd to your Windsurf MCP configuration:\n\n```json\n{\n   \"mcpServers\": {\n      \"timing\": {\n         \"command\": \"npx\",\n         \"args\": [\"-y\", \"@a-und-b/timing-mcp\"],\n         \"env\": {\n            \"TIMING_API_KEY\": \"your-timing-api-key\"\n         }\n      }\n   }\n}\n```\n\n</details>\n\n<details>\n<summary><strong>Claude Code (CLI)</strong></summary>\n\nAdd the MCP server to Claude Code:\n\n```bash\nclaude mcp add -e TIMING_API_KEY=\"your-timing-api-key\" timing -- npx -y @a-und-b/timing-mcp\n```\n\n</details>\n\n<details>\n<summary><strong>Gemini CLI</strong></summary>\n\nConfigure Gemini CLI with MCP support:\n\n```json\n{\n   \"mcpServers\": {\n      \"timing\": {\n         \"command\": \"npx\",\n         \"args\": [\"-y\", \"@a-und-b/timing-mcp\"],\n         \"env\": {\n            \"TIMING_API_KEY\": \"your-timing-api-key\"\n         }\n      }\n   }\n}\n```\n\n</details>\n\n<details>\n<summary><strong>Kiro</strong></summary>\n\n1. Go to `Kiro` > `MCP Servers`\n2. Add new MCP server by clicking `+ Add`\n3. Paste the configuration below:\n\n```json\n{\n  \"mcpServers\": {\n    \"timing\": {\n    \"command\": \"npx\",\n    \"args\": [\n      \"-y\",\n      \"@a-und-b/timing-mcp\"\n    ],\n    \"env\": {\n       \"TIMING_API_KEY\": \"your-timing-api-key\"\n    },\n    \"disabled\": false,\n    \"autoApprove\": []\n    }\n  }\n}\n```\n\n4. Click `Save` to apply changes\n</details>\n\n<details>\n<summary><strong>LM Studio</strong></summary>\n\n1. Go to `Program` (right side) > `Install` > `Edit mcp.json`\n2. Paste the configuration below:\n```json\n{\n  \"mcpServers\": {\n    \"timing\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"@a-und-b/timing-mcp\"],\n       \"env\": {\n          \"TIMING_API_KEY\": \"your-timing-api-key\"\n       }\n    }\n  }\n}\n```\n3. Click `Save` to apply changes\n4. Toggle MCP server on/off from the right hand side (under `Program`) or by clicking the plug icon at the bottom of the chat box\n\n</details>\n\n## 🔑 Timing API Setup\n\n### Getting Your API Key\n\n1. **Log into your Timing account**\n2. **Navigate to API settings:**\n   - Go to **Integrations** → **API Keys**\n   - Or visit: [https://web.timingapp.com/integrations/tokens](https://web.timingapp.com/integrations/tokens)\n3. **Generate a new API key** (if you don't have one)\n4. **Copy the API key** and add it to your MCP client configuration\n\n### Environment Variables\n\nYou can set environment variables in several ways:\n\n**Option 1: System Environment Variables**\n```bash\nexport TIMING_API_KEY=\"your-timing-api-key\"\n```\n\n**Option 2: .env File (for local development)**\n```env\nTIMING_API_KEY=your-timing-api-key\n```\n\n**Option 3: MCP Client Configuration (recommended)**\nUse the `env` section in your MCP client configuration as shown above.\n\n## 🛠️ Available Tools\n\n### Local Database\n> [!note]\n> This feature only works when the MCP server is running on the same machine as the Timing app (macOS).\n\n| Tool | Description | Parameters |\n|------|-------------|------------|\n| `timing_get_granular_app_activity` | Get granular usage (window titles, paths) from local DB | `from`, `to` (date strings or relative terms like 'today', 'yesterday'), `limit` |\n\n### Projects\n\n| Tool | Description | Parameters |\n|------|-------------|------------|\n| `timing_list_projects` | List all projects with optional filtering | `title`, `hideArchived`, `teamId` (all optional) |\n| `timing_list_projects_hierarchy` | Get hierarchical project structure | `teamId` (optional) |\n| `timing_project` | Get project details | `id` |\n| `timing_create_project` | Create a new project | `title`, `parent`, `color`, `notes`, `productivityScore`, etc. |\n| `timing_update_project` | Update an existing project | `projectId`, various optional fields |\n| `timing_delete_project` | Delete a project | `projectId` |\n\n### Time Entries\n\n| Tool | Description | Parameters |\n|------|-------------|------------|\n| `timing_list_time_entries` | List time entries with filtering | `startDateMin`, `startDateMax`, `projects`, `searchQuery`, etc. |\n| `timing_time_entry` | Get time entry details | `id` |\n| `timing_create_time_entry` | Create a new time entry | `project`, `title`, `startDate`, `endDate`, `notes`, `billingStatus` |\n| `timing_update_time_entry` | Update an existing time entry | `timeEntryId`, various optional fields |\n| `timing_delete_time_entry` | Delete a time entry | `timeEntryId` |\n| `timing_start_time_entry` | Start a new timer | `project`, `title`, `startDate`, `notes` |\n| `timing_stop_time_entry` | Stop the current timer | (no parameters) |\n| `timing_batch_update_time_entries` | Batch update multiple time entries | `timeEntryIds`, `billingStatus`, `customFields` |\n\n### Teams\n\n| Tool | Description | Parameters |\n|------|-------------|------------|\n| `timing_list_teams` | List all teams | (no parameters) |\n| `timing_team` | Get team details | `id` |\n\n### Reports\n\n| Tool | Description | Parameters |\n|------|-------------|------------|\n| `generate_timing_report` | Generate comprehensive report | `startDateMin`, `startDateMax`, `projects`, `columns`, etc. |\n\n## 🎯 Available Prompts\n\nThe Timing MCP server provides 7 intelligent prompts that orchestrate multiple tools to deliver comprehensive insights:\n\n| Prompt | Description | Key Parameters |\n|--------|-------------|----------------|\n| `weekly_time_report` | Generates detailed weekly time tracking report with project breakdown | `week_start`, `include_project_breakdown` |\n| `project_time_analysis` | Analyzes time spent across projects with insights | `project_ids`, `time_period` |\n| `productivity_insights` | Analyzes productivity patterns and provides recommendations | `analysis_period`, `focus_area` |\n| `billing_summary` | Generates billing status summary with revenue insights | `start_date`, `end_date`, `include_status_breakdown` |\n| `time_entry_audit` | Audits time entries for completeness and accuracy | `start_date`, `end_date`, `check_running_entries` |\n| `project_hierarchy_overview` | Visualizes project structure and time distribution | `team_id`, `include_archived` |\n| `monthly_time_summary` | Creates comprehensive monthly time summary with trends | `month`, `year`, `include_comparisons` |\n\n### Prompt Examples\n\n**Weekly Time Report:**\n```json\n{\n  \"name\": \"weekly_time_report\",\n  \"arguments\": {\n    \"week_start\": \"2024-01-15\",\n    \"include_project_breakdown\": true\n  }\n}\n```\n\n**Project Time Analysis:**\n```json\n{\n  \"name\": \"project_time_analysis\",\n  \"arguments\": {\n    \"project_ids\": \"1,2,3\",\n    \"time_period\": \"last_month\"\n  }\n}\n```\n\n**Billing Summary:**\n```json\n{\n  \"name\": \"billing_summary\",\n  \"arguments\": {\n    \"start_date\": \"2024-01-01\",\n    \"end_date\": \"2024-01-31\",\n    \"include_status_breakdown\": true\n  }\n}\n```\n\n## 📝 Tool Examples\n\n### Get Granular Activity\n```json\n{\n  \"name\": \"timing_get_granular_app_activity\",\n  \"arguments\": {\n    \"from\": \"yesterday\",\n    \"to\": \"today\",\n    \"limit\": 10\n  }\n}\n```\n\n### List Projects\n\n```json\n{\n  \"name\": \"timing_list_projects\",\n  \"arguments\": {\n    \"hideArchived\": true\n  }\n}\n```\n\n### Create Project\n\n```json\n{\n  \"name\": \"timing_create_project\",\n  \"arguments\": {\n    \"title\": \"Website Redesign\",\n    \"color\": \"#FF0000\",\n    \"productivityScore\": 1,\n    \"notes\": \"Main client project\"\n  }\n}\n```\n\n### List Time Entries\n\n```json\n{\n  \"name\": \"timing_list_time_entries\",\n  \"arguments\": {\n    \"startDateMin\": \"2024-01-01T00:00:00+00:00\",\n    \"startDateMax\": \"2024-01-31T23:59:59+00:00\",\n    \"includeProjectData\": true\n  }\n}\n```\n\n### Create Time Entry\n\n```json\n{\n  \"name\": \"timing_create_time_entry\",\n  \"arguments\": {\n    \"project\": \"/projects/1\",\n    \"title\": \"Frontend Development\",\n    \"startDate\": \"2024-01-15T09:00:00+00:00\",\n    \"endDate\": \"2024-01-15T17:00:00+00:00\",\n    \"notes\": \"Implemented new features\",\n    \"billingStatus\": \"billable\"\n  }\n}\n```\n\n### Start Timer\n\n```json\n{\n  \"name\": \"timing_start_time_entry\",\n  \"arguments\": {\n    \"project\": \"/projects/1\",\n    \"title\": \"Working on feature\",\n    \"notes\": \"Starting development\"\n  }\n}\n```\n\n### Generate Report\n\n```json\n{\n  \"name\": \"generate_timing_report\",\n  \"arguments\": {\n    \"startDateMin\": \"2024-01-01\",\n    \"startDateMax\": \"2024-01-31\",\n    \"columns\": [\"title\", \"project\", \"duration\"],\n    \"timespanGroupingMode\": \"day\"\n  }\n}\n```\n\n## 🔧 Advanced Configuration\n\n<details>\n<summary><strong>Local Development</strong></summary>\n\nIf you want to run from source:\n\n```bash\ngit clone https://github.com/a-und-b/timing-mcp.git\ncd timing-mcp\nnpm install\nnpm run build\nnpm start\n```\n\nThen configure your MCP client to use the local path:\n\n```json\n{\n  \"mcpServers\": {\n    \"timing\": {\n      \"command\": \"node\",\n      \"args\": [\"/path/to/timing-mcp/dist/index.js\"],\n      \"env\": {\n        \"TIMING_API_KEY\": \"your-timing-api-key\"\n      }\n    }\n  }\n}\n```\n\n</details>\n\n<details>\n<summary><strong>Docker Support</strong></summary>\n\n```dockerfile\nFROM node:18-alpine\nWORKDIR /app\nRUN npm install -g @a-und-b/timing-mcp\nENV TIMING_API_KEY=\"\"\nCMD [\"timing-mcp\"]\n```\n\n</details>\n\n## 🔍 Troubleshooting\n\n### Common Issues\n\n**❌ Authentication Error:**\n```\nTIMING_API_KEY environment variable is not set\n```\n- Verify your API key is correct\n- Check if the API key is properly set in environment variables\n- Ensure the key hasn't expired\n\n**❌ Node.js Version Error:**\n```\nThis package requires Node.js >= 18.0.0\n```\n- Update Node.js to version 18 or higher\n- Check your version: `node --version`\n\n**❌ npx Connection Issues:**\n```\nError: Cannot find module '@a-und-b/timing-mcp'\n```\n- Ensure you have internet connection\n- Try: `npx --yes @a-und-b/timing-mcp`\n- Clear npx cache: `npx clear-npx-cache`\n\n**❌ MCP Client Not Finding Tools:**\n- Restart your MCP client after configuration changes\n- Check that environment variables are properly set\n- Verify JSON configuration syntax is correct\n\n### Debug Mode\n\nFor debugging, you can run the server with additional logging:\n\n```bash\nNODE_ENV=development npx -y @a-und-b/timing-mcp\n```\n\n### Testing Connection\n\nYou can test the server manually:\n\n```bash\necho '{\"jsonrpc\": \"2.0\", \"id\": 1, \"method\": \"tools/list\"}' | npx -y @a-und-b/timing-mcp\n```\n\n## 🌟 Features\n\n- **🖥️ Local Data Access:** Direct access to local SQLite database for granular activity data (window titles, file paths)\n- **✅ Full CRUD Support:** Create, read, update, and delete across projects and time entries\n- **🔄 Automatic Validation:** Input validation using Zod schemas\n- **📊 Comprehensive Reports:** Generate detailed reports with flexible filtering\n- **⏱️ Timer Control:** Start and stop timers for time tracking\n- **💰 Billing Status:** Track billing status (billable, not_billable, billed, paid)\n- **🏗️ Project Hierarchy:** Access hierarchical project structures\n- **🧩 Comprehensive Tools:** 18 specialized tools for different use cases\n- **🎯 Intelligent Prompts:** 7 AI-powered prompts for complex analysis and insights\n- **🌐 Multi-Client Support:** Works with all major MCP clients\n- **📝 Custom Fields:** Support for custom fields on projects and time entries\n\n## 🤝 Contributing\n\n1. Fork the repository\n2. Create a feature branch: `git checkout -b feature-name`\n3. Make your changes and add tests\n4. Submit a pull request\n\n## 📄 License\n\nMIT License - see [LICENSE](LICENSE) file for details.\n\n## 🙏 Acknowledgments\n\nThis project is a fork of [tomoyanakano/timing-mcp-server](https://github.com/tomoyanakano/timing-mcp-server), extended with comprehensive capabilities, prompts support, and production-ready structure.\n\n## 🆘 Support\n\n- **Timing API Issues:** [Timing API Documentation](https://web.timingapp.com/llms.txt)\n- **MCP Protocol:** [MCP Documentation](https://modelcontextprotocol.io/)\n- **This Package:** [GitHub Issues](https://github.com/a-und-b/timing-mcp/issues)\n","readmeFilename":"README.md"}