Skip to content

README.md

Latest commit

 

History

History
222 lines (150 loc) · 9.09 KB

README.md

File metadata and controls

222 lines (150 loc) · 9.09 KB

timing-local-mcp

A local MCP server that gives AI assistants read-only access to the Timing SQLite database on macOS — Intel and Apple Silicon. Ask your AI to summarise your day, aggregate time by app or project, spot patterns in your work habits, and explore the database schema. The MCP server queries your database directly on your Mac — no cloud API, no authentication required. Note that when used with a cloud-based AI service such as Claude, query results are sent to that service's servers for processing. For fully local processing, connect this server to a local LLM tool such as LM Studio.

Scope — This server is intentionally read-only. There are no plans to add write capabilities or broader Timing integration. If you need more than read access, look for other MCP servers.

Disclaimer — This is an independent open-source project. It is not affiliated with, endorsed by, or supported by Timing Software GmbH, the developer of Timing.

What you can ask

Once set up, try questions like these in Claude:

  • "How much time did I spend in each app today?"
  • "Show me my top 5 most-used apps this week."
  • "How many hours did I log on the Acme project last month?"
  • "What was I working on yesterday between 2 pm and 4 pm?"
  • "Which days this week had the most tracked time?"

Prerequisites

  • macOS — Intel or Apple Silicon
  • Timing installed and launched at least once so its database exists. Timing is available:
    • Directly from timingapp.com
    • As part of a Setapp subscription (affiliate link — new subscribers get a 30-day free trial instead of the standard 7 days)
  • Python 3.10+ — check with python3 --version. If not installed, use Homebrew: 
    /bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"
brew install python
  • Claude Desktop and/or Claude Code CLI, or a local LLM tool such as LM Studio or Jan for fully local processing

Setup

1. Clone the repo

git clone https://github.com/DamienSchreurs/timing-local-mcp.git
cd timing-local-mcp

2. Create a virtual environment and install dependencies

python3 -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt

A virtual environment is required because both Claude Desktop and Claude Code launch the server as a subprocess. They must point to the Python binary inside .venv/ so the mcp package is found regardless of what is installed system-wide.

3. Note your absolute paths

You will need these in the registration steps below:

echo "Python: $(pwd)/.venv/bin/python"
echo "Script: $(pwd)/timing_mcp.py"

Claude Desktop app

Edit ~/Library/Application Support/Claude/claude_desktop_config.json (create the file if it doesn't exist) and add the timing-local entry inside mcpServers:

{
  "mcpServers": {
    "timing-local": {
      "command": "/absolute/path/to/timing-local-mcp/.venv/bin/python",
      "args": ["/absolute/path/to/timing-local-mcp/timing_mcp.py"]
    }
  }
}

Replace the paths with the values printed above. Then quit and relaunch Claude Desktop. The server will appear in the tool list when starting a new conversation.

Claude Code CLI

Run this from inside the repo directory:

claude mcp add timing-local "$(pwd)/.venv/bin/python" -- "$(pwd)/timing_mcp.py"

Verify it's connected:

claude mcp list

You should see timing-local: ... ✓ Connected.

LM Studio (fully local)

LM Studio can act as an MCP client, keeping all processing on your machine — no data is sent to any external server.

  1. Open LM Studio and go to Settings → Developer.
  2. Locate the MCP Servers configuration and add the timing-local entry:
{
  "mcpServers": {
    "timing-local": {
      "command": "/absolute/path/to/timing-local-mcp/.venv/bin/python",
      "args": ["/absolute/path/to/timing-local-mcp/timing_mcp.py"]
    }
  }
}

Replace the paths with the values printed in step 3 above. Restart LM Studio and load any model that supports tool calling — the timing-local tools will be available in your chat session.

Note — MCP support in LM Studio requires version 0.3.5 or later. The exact menu path may vary slightly across versions; look for a Developer or Tools section in Settings.

Jan (fully local)

Jan is a popular open-source alternative to LM Studio with MCP support. Jan terminates the subprocess if it receives any output on stderr; timing_mcp.py silences FastMCP's log output at the Python level so nothing reaches Jan's stderr pipe.

In Jan, go to Settings → MCP Servers → Add and configure the server as follows:

Field Value
Server Name timing-local
Transport STDIO
Command /absolute/path/to/timing-local-mcp/.venv/bin/python
Arguments /absolute/path/to/timing-local-mcp/timing_mcp.py

Replace the paths with the values printed in step 3 above. Save, toggle the server on, and the three tools will appear in the Available Tools list. Use a model that supports tool calling (e.g. Jan v3.5, Llama 3.1, Qwen 2.5).

Alternatively, edit ~/Library/Application Support/Jan/data/mcp_config.json directly and add the timing-local entry inside mcpServers:

{
  "mcpServers": {
    "timing-local": {
      "active": true,
      "command": "/absolute/path/to/timing-local-mcp/.venv/bin/python",
      "args": ["/absolute/path/to/timing-local-mcp/timing_mcp.py"],
      "env": {}
    }
  }
}

Tools

Tool Description
list_timing_tables() Lists all tables in the Timing SQLite database
get_timing_schema(table_name) Returns column definitions for a table
query_timing_db(sql_query, limit) Executes a read-only SQL query; limit defaults to 200 rows

AI agent instructions

The repo includes schema documentation and SQL conventions so Claude queries the database correctly. How to load them depends on the client:

Claude Code CLI — reads CLAUDE.md automatically at session start. No action needed.

Claude Desktop — import timing-local-mcp.skill via Customize → Skills → + → Create skill → Upload a skill. Enable it in any conversation where you want to query Timing.

Other AI agents (e.g. OpenClaw) — use SKILL.md, which follows the same format. Attach it or add it as a context document according to your tool's instructions.

Troubleshooting

Server not connecting

  • Make sure you ran python3 -m venv .venv && pip install -r requirements.txt inside the repo.
  • Double-check that the paths in your config point to .venv/bin/python and timing_mcp.py — they must be absolute, not relative.
  • After editing claude_desktop_config.json, fully quit and relaunch Claude Desktop (⌘Q, not just closing the window).

No data returned / empty results

  • Timing must have been opened at least once to create its SQLite database.
  • If you recently migrated to a new Mac, Timing may store its database in a different location until it has synced. Open Timing and let it complete its initial setup.

FAQ

Who is this for? Anyone who uses Timing on macOS and wants to explore their time tracking data through natural language, without writing SQL manually. Works with Claude (Desktop or Code CLI) and with local LLM tools such as LM Studio for fully private processing.

On which Macs does it run? Any Mac running macOS with Timing installed — both Intel and Apple Silicon are supported.

What are the prerequisites? macOS, Timing installed and launched at least once, Python 3.10+, and at least one Claude client (Desktop app or Code CLI).

Is my data sent to the cloud? The MCP server runs entirely on your machine and queries the SQLite database locally — your data never leaves your Mac via this server. However, when using a cloud-based AI service such as Claude Desktop or Claude Code, the query results are sent to that service's servers for processing. For fully local processing with no data leaving your machine at all, connect this server to a local LLM tool such as LM Studio or Jan.

Is this affiliated with or endorsed by the Timing developers? No. This is an independent open-source project with no affiliation to Timing Software GmbH.

Which versions of Timing are supported? Tested with Timing 2025.9.1 and 2026.2 on macOS Sequoia 15.7.4 and Sonoma 14.8.5.

Do you plan to extend the capabilities beyond read-only? No. Read-only access is intentional and there are no plans to add write capabilities. If you need more, search for alternative Timing MCP servers.

Does it work with AI clients other than Claude Desktop and Claude Code? Yes. Any agent that accepts a skill or context document can use SKILL.md, which contains the same schema and query instructions.

License

MIT — see LICENSE.