timesheet-mcp

A local, MCP-only timesheet application. There is no UI of its own — Claude (or any other MCP client) is the interface. Users ask their AI assistant to log hours, correct entries, run monthly reports, and pull the numbers needed to invoice customers. The server's job is correct data storage, filtering/aggregation, and Finnish-holiday-aware working-time math — not natural-language parsing (the AI client is responsible for turning "log 3h on Tempo yesterday" into a structured tool call).

Tech stack

• Python 3.11+

• mcp (official Python MCP SDK, FastMCP-style server)

• holidays for Finnish public holidays

• SQLite (stdlib) for storage

• uv for dependency/venv management

• pytest for tests

Related MCP server: TimePRO MCP Server

Setup

uv sync

Testing

Verify the project scaffolds correctly (no tests yet, but confirms the package is importable and dependencies resolve):

pytest --collect-only

Run all tests against a temp SQLite database:

pytest

Run specific test modules:

pytest tests/test_models.py

Docker

Build the image:

docker build -t timesheet-mcp .

Run the MCP server (stdio transport — requires -i for stdin):

docker run -i --rm \
  -v ./data:/app/data \
  -v ./logs:/app/logs \
  timesheet-mcp

Mount ./data and ./logs from the host so the SQLite database and log file persist across container restarts and rebuilds.

Environment variables can be passed with -e (defaults are sane): TIMESHEET_DB_PATH, TIMESHEET_LOG_LEVEL, TIMESHEET_LOG_STDERR.

Install for Claude Desktop (single user, local)

Prerequisites: Docker and git.

git clone https://github.com/erkkiat/timesheet-mcp.git
cd timesheet-mcp
docker build -t timesheet-mcp:latest .
mkdir -p data logs

Add a timesheet entry under the top-level mcpServers key in your Claude Desktop config (~/Library/Application Support/Claude/claude_desktop_config.json on macOS) — merge it in alongside anything else already in that file, and replace /absolute/path/to/timesheet-mcp with wherever you cloned this repo:

{
  "mcpServers": {
    "timesheet": {
      "command": "/absolute/path/to/timesheet-mcp/run-mcp.sh",
      "args": []
    }
  }
}

Restart Claude Desktop. The timesheet server should now be available, backed by a SQLite database at data/timesheet.db on your own machine — nothing leaves your computer.

run-mcp.sh wraps the plain docker run -i --rm --name timesheet-mcp ... command with one extra step: before starting, it force-clears any existing timesheet-mcp container. The fixed --name is what stops Docker from ever silently running two instances at once, but it has a failure mode of its own — if a previous instance ever gets stuck without actually exiting, that same name blocks a fresh one from starting, so Desktop's reconnect attempt fails with a name conflict instead of just working. Since Desktop only invokes this script when it needs a working connection right now, any pre-existing container by this name at that moment is presumed stale, so the wrapper clears it first. SQLite's WAL mode means an abrupt restart mid-write rolls back cleanly rather than corrupting the database. If you'd rather run the container by hand for testing, the plain docker run command in the Docker section above still works the same way — run-mcp.sh is purely a convenience/self-healing layer for Desktop, not a requirement.

Project status

1.0 — the full MCP tool surface (customers, projects, people, time entries, Finnish-holiday-aware monthly reports) is implemented, tested, Dockerized, and verified end-to-end including under concurrent load. See PLAN.md for the design spec.