Wakatime

You run an MCP server that analyzes your WakaTime data and exposes rich, actionable analytics through either a direct HTTP endpoint or a proxy-enabled, authenticated route. This lets you integrate coding activity insights into your own dashboards and tooling with flexible access modes.

How to use

Choose your access method based on your hosting needs. In direct mode you connect to a fast, streamable HTTP endpoint at http://localhost:8000/mcp. In proxy mode you run through mcp-proxy and expose the server via SSE/HTTP, with an optional authentication layer provided by a proxy service such as Caddy. When using proxy mode, you protect the MCP endpoint with a strong token that you supply as MCP_AUTH_KEY.

Connect with an MCP client to fetch analytics like coding stats, activity breakdowns, and current day status. You can use the available tools to query data ranges (e.g., last 7 days, last 30 days, all time) and to list or search tracked projects. In direct mode, target http://localhost:8000/mcp. In proxy mode, target the SSE endpoint exposed by the proxy (for example, http://localhost:8770/sse). If you’re using the proxy, include your MCP_AUTH_KEY in the Authorization header or as X-API-Key / Api-Key headers as required by your client.

How to install

Prerequisites: you need Python and the uvx runtime available on your system.

Development (direct mode) steps you can follow to run the server locally:

# Install/prepare
# You will run the server with the WakaTime API key you obtain from your account
# Then start the server directly using uv
WAKATIME_API_KEY="your_wakatime_api_key_here" uv run -- python src/server.py

Configuration and deployment notes

You configure the server using environment variables. The required variable is WAKATIME_API_KEY (your WakaTime API key). In proxy/self-hosted setups, you also provide MCP_AUTH_KEY as a token for authentication. You can create a .env file for convenience, or export variables in your shell before starting the server.

Direct mode uses the following URL by default: http://localhost:8000/mcp. Proxy mode is set up through mcp-proxy and Common HTTP endpoints are exposed behind an authentication layer (for example, via Caddy). The internal, unauthenticated endpoints run on http://localhost:8767/ while the authenticated proxy endpoints run on http://localhost:8770/ with an auth layer.

Security and maintenance

Generate a strong authentication key for the proxy mode to prevent unauthorized access. A recommended command to generate a key is openssl rand -hex 32. Never expose the unauthenticated port to the public Internet. When using a proxy, keep the auth layer enabled and rotate keys periodically.

If you plan to run this in a persistent environment, you can enable systemd services to keep the servers running across reboots. You can also publish the proxy port with tunneling or a reverse proxy as appropriate for your network.

Troubleshooting tips

• Ensure WAKATIME_API_KEY is correct and has the necessary permissions in your WakaTime account.
• If you are using proxy mode, verify that MCP_AUTH_KEY is set and that client requests include the proper Authorization or API-Key headers.
• Check that the HTTP endpoint is reachable at http://localhost:8000/mcp when running in direct mode.
• Confirm that the proxy endpoints are up and that the internal server is reachable from the proxy.
• Review startup logs for any missing dependencies or environment variables and adjust accordingly.

Available tools

get_coding_stats

Fetch detailed coding statistics for a specified range such as last 7 days, last 30 days, last 6 months, last year, or all time.

get_summary

Get an activity breakdown for a specific date range and optional project filter.

get_all_time

Retrieve total coding time since account creation, optionally scoped to a project.

get_status_bar

Retrieve the current day status suitable for editor status bars.

list_projects

List or search tracked projects to see what is being analyzed.