timetracker

TimeTracker MCP provides a conversational-first time tracking experience. You can manage clients, projects, and time entries entirely through natural language commands via MCP-compatible clients. Start a timer, pause or stop it, create or update clients and projects, and generate personal reports or earnings summaries. The web dashboard remains available as an optional visualization layer for quick status checks, charts, and light timer controls, but all business logic is accessible through conversational interactions.

To use it, connect with an MCP client (for example a chat interface or an integration that supports MCP). Use commands like create_client, list_projects, start_time_tracking, or get_time_summary to interact with the system. Time entries are private per user, while clients and projects are shared resources within the organization, allowing collaborative management without compromising individual privacy. If you prefer visual inspection, you can switch to the web dashboard for charts and dashboards, while continuing to perform operations via MCP commands in your conversational client.

Prerequisites:

• Node.js 18+
• pnpm or npm
• PostgreSQL database
• Optional Redis for production caching/session storage

1. Clone the repository and install dependencies

git clone https://github.com/lumile/timetracker-mcp.git
cd timetracker-mcp
pnpm install

2. Configure environment

• Copy the example env and update values

cp .env.example .env.local

• Ensure required environment variables are set in .env.local, including DATABASE_URL, AUTH_SECRET, and any Better Auth configuration if used

3. Prepare the database

pnpm db:generate
pnpm db:migrate
pnpm db:seed

4. Start the server

pnpm dev

5. Open the MCP-enabled interface and begin issuing conversational commands to manage time tracking. The web dashboard can be accessed if enabled via the server configuration.

Environment variables to watch:

• DATABASE_URL: PostgreSQL connection string
• REDIS_URL: Optional Redis connection for sessions/cache
• AUTH_SECRET: Secret used for authentication tokens
• BETTER_AUTH_CONFIG: Settings for Better Auth integration (PKCE, etc.)

Common issues:

• Ensure the database migrations have run after updating the schema
• If the MCP client cannot reach the server, verify NETWORK and DATABASE_URL connectivity
• For production deployments, consider enabling Redis, configuring proper TLS, and setting appropriate CORS policies for the web dashboard

Tips:

• Use the MCP tools directly via chat clients to reduce context switching
• Combine MCP commands to batch operations (e.g., create_client followed by create_project) for smoother setup
• The dashboard is optional; most daily work can be accomplished through the conversational interface