rescuetime

RescueTime MCP Server provides a FastMCP-compatible interface to access RescueTime data and manage productivity tools through MCP commands. Built in Python using the RescueTime API, the server exposes core features such as retrieving productivity data, daily summaries, alerts, and highlights, as well as managing focus sessions and logging offline time. It also offers convenience functions like real-time productivity scores, top distractions, and the most recent daily summaries. Once running, you can interact with it via MCP clients (e.g., Claude Desktop) using natural language prompts or scripted requests to fetch data, start or stop focus sessions, or create records in RescueTime.

To use it, configure the MCP server with your RescueTime API key (via a .env file or Claude Desktop config), then start the server using the configured command. After startup, you can query for data such as your productivity data for today or a date range, request daily or latest summaries, manage alerts, or initiate focus sessions. The server also supports creating highlights and logging offline time, enabling a comprehensive productivity workflow through the MCP interface.

Prerequisites

• Python 3.9 or higher
• Git
• Internet access to install dependencies

Step-by-step installation

1. Clone the repository git clone https://github.com/ebowman/rescuetime-mcp.git cd rescuetime-mcp

2. Set up a virtual environment python3 -m venv venv source venv/bin/activate # On Windows: venv\Scripts\activate

3. Install dependencies pip install -r requirements.txt

4. Install the package in editable mode (optional but common for development) pip install -e .

5. Prepare your RescueTime API key

   • Create a .env file in the project root with: RESCUETIME_API_KEY=your_api_key_here
   • Alternatively, set the API key via Claude Desktop config or environment variable: export RESCUETIME_API_KEY=your_api_key_here

6. Run or configure the MCP server as described in the mcp_config section The default recommended command is: python -m rescuetime_mcp.server

7. (Optional) If you plan to use Claude Desktop, configure the MCP server in claude_desktop_config.json as shown in the README.

Notes

• If you prefer not to use a .env file, you can pass the API key directly through config using the env block (see mcp_config example).
• Windows users should adapt paths and activation commands accordingly.

Tips and common issues:

• Ensure your RescueTime API key is kept secret. Do not commit it to version control.
• The server relies on the RescueTime API; if API limits are reached or credentials are invalid, requests may fail with clear error messages.
• The project uses FastMCP with type safety via Pydantic; ensure Python typing is respected and linters are run as part of development.
• If you encounter import or module resolution issues, activate the virtual environment and verify that rescuetime_mcp.server is importable from your Python path.
• For Claude Desktop users, the recommended configuration path in Step 5 of the README shows how to point to your local server; you can also embed environment variables in the config under env.
• On Windows, adapt virtual environment and path conventions (venv/Scripts/activate).
• If you need to test integration with the real RescueTime API, set RESCUETIME_API_KEY_REAL as described in the Advanced Configuration section of the README and run integration tests.
• The server exposes core and convenience commands; think of Core Functions as primary data access and actions (data retrieval, focus management, logging), while Convenience Functions provide quick-read capabilities like today’s score or top distractions.