npm package: @mnicole-dev/rize-mcp-server
Description: MCP server for the Rize time tracking GraphQL API
Latest version: 1.0.1

# @mnicole-dev/rize-mcp-server

A [Model Context Protocol (MCP)](https://modelcontextprotocol.io) server for the [Rize](https://rize.io) time tracking GraphQL API. Track focus sessions, monitor app usage, manage projects/tasks/clients, and analyze productivity from any MCP-compatible client.

## Features

**34 tools** covering the full Rize GraphQL API:

### User (1 tool)
| Tool | Description |
|------|-------------|
| `get-me` | Get the authenticated user profile |

### Summaries & Analytics (3 tools)
| Tool | Description |
|------|-------------|
| `get-summaries` | Get time tracking summaries (focus, break, meeting, tracked time) with daily/weekly/monthly breakdown and optional category analysis |
| `get-apps-and-websites` | Get app and website usage for a time range |
| `get-categories` | Get time spent by category |

### Sessions (7 tools)
| Tool | Description |
|------|-------------|
| `list-sessions` | List focus/break/meeting sessions |
| `get-current-session` | Get the currently active session |
| `start-session-timer` | Start a focus, break, or meeting timer |
| `stop-session-timer` | Stop the current timer |
| `extend-current-session` | Extend the current timer by N minutes |
| `create-session` | Create a manual session entry |
| `update-session` | Update a session |
| `delete-session` | Delete a session |

### Projects (5 tools)
| Tool | Description |
|------|-------------|
| `list-projects` | List all projects with time spent and budgets |
| `get-project` | Get project details |
| `create-project` | Create a project (with keywords, budget, client) |
| `update-project` | Update a project |
| `delete-project` | Delete a project |

### Tasks (4 tools)
| Tool | Description |
|------|-------------|
| `list-tasks` | List all tasks |
| `create-task` | Create a task (with project, assignee, keywords) |
| `update-task` | Update a task |
| `delete-task` | Delete a task |

### Clients (4 tools)
| Tool | Description |
|------|-------------|
| `list-clients` | List all clients |
| `create-client` | Create a client (with hourly rate, keywords) |
| `update-client` | Update a client |
| `delete-client` | Delete a client |

### Time Entries (9 tools)
| Tool | Description |
|------|-------------|
| `list-project-time-entries` | List time entries for projects |
| `create-project-time-entry` | Log time against a project |
| `delete-project-time-entry` | Delete a project time entry |
| `list-task-time-entries` | List time entries for tasks |
| `create-task-time-entry` | Log time against a task |
| `delete-task-time-entry` | Delete a task time entry |
| `list-client-time-entries` | List time entries for clients |
| `create-client-time-entry` | Log time against a client |
| `delete-client-time-entry` | Delete a client time entry |

## Requirements

- Node.js 18+
- A Rize account with API access
- An API key from [Settings > API](https://app.rize.io) in your Rize account

## Installation

```bash
npm install -g @mnicole-dev/rize-mcp-server
```

Or run directly with `npx`:

```bash
npx @mnicole-dev/rize-mcp-server
```

## Configuration

Set the `RIZE_API_KEY` environment variable:

```bash
export RIZE_API_KEY=your-api-key
```

### Claude Code

Add to your `~/.claude.json`:

```json
{
  "mcpServers": {
    "rize": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@mnicole-dev/rize-mcp-server"],
      "env": {
        "RIZE_API_KEY": "your-api-key"
      }
    }
  }
}
```

### Claude Desktop

Add to your config (`~/Library/Application Support/Claude/claude_desktop_config.json` on macOS):

```json
{
  "mcpServers": {
    "rize": {
      "command": "npx",
      "args": ["-y", "@mnicole-dev/rize-mcp-server"],
      "env": {
        "RIZE_API_KEY": "your-api-key"
      }
    }
  }
}
```

## Examples

### Weekly summary

```
> Show me my time tracking summary for this week
```

Calls `get-summaries` — returns tracked time, focus time, break time, meeting time, daily breakdown, and category analysis.

### Start a focus session

```
> Start a 45 minute focus session for deep work
```

Calls `start-session-timer` with:
```json
{
  "type": "focus",
  "length": 45,
  "intention": "deep work"
}
```

### Check what apps you used

```
> What apps did I use today?
```

Calls `get-apps-and-websites` with today's date range — shows time spent per app with category labels.

### Log time to a project

```
> Log 2 hours on project abc123 from 9am to 11am today
```

Calls `create-project-time-entry` with the project ID and time range.

## How it works

1. The MCP client sends a tool call to the server via stdio
2. The server translates the call into a GraphQL query/mutation
3. The request is sent to `https://api.rize.io/api/v1/graphql` with Bearer token auth
4. The response is formatted as human-readable text and returned

## Development

```bash
git clone https://github.com/mnicole-dev/rize-mcp-server.git
cd rize-mcp-server
pnpm install
pnpm dev          # Run with tsx (requires RIZE_API_KEY)
pnpm build        # Build to dist/
```

## License

MIT