# Pomodoro Ai MCP

> Pomodoro Ai MCP is an open-source MCP server for time tracking. Pomodoro focus timer and productivity stats as an MCP server for AI assistants. It runs locally on your machine and is started by your AI client.

- **Kind:** MCP server
- **Pricing:** Open source
- **Platforms:** CLI, self-hosted, API
- **Repository:** https://github.com/csoai-org/pomodoro-ai-mcp
- **MCP Registry name:** io.github.CSOAI-ORG/pomodoro-ai-mcp
- **Categories:** [time tracking](https://ai-powered.com/categories/time-tracking)
- **Listing updated:** 2026-11-18

## About

The README says this MCP server lets an AI assistant manage Pomodoro focus sessions, breaks and basic productivity analytics. It installs from PyPI as a stdio server and is configured by adding a single entry to an MCP client config such as Claude Desktop.

The README's examples name three tools, start_session, stop_session and get_stats, which the assistant can call in conversation. No other tool names are listed, so the full set of capabilities is not documented in the repository.

The project is aimed at developers and users who already work with an MCP-compatible assistant and want time-boxed focus tracking inside that workflow. The repository is MIT-licensed and free to self-host. The README also promotes the vendor's paid compliance services, which are separate from this server.

## Features

- **Focus session control:** Starts and stops Pomodoro work sessions through named tool calls from an AI client.
- **Break management:** Handles break periods alongside focus sessions as part of the Pomodoro cycle.
- **Productivity statistics:** Exposes a get_stats tool for reviewing session-based productivity figures.
- **Stdio installation:** Runs over stdio and installs with pip or uvx, with a ready-to-paste client config.

## Good for

- Start and stop focus sprints from within an AI chat without switching apps
- Review how many focus sessions were completed over a period
- Add time-boxed work intervals to an assistant-driven daily planning routine

## Install

### Claude Code (Terminal)

```sh
claude mcp add pomodoro-ai-mcp -- uvx pomodoro-ai-mcp
```

### Claude Desktop (claude_desktop_config.json)

```json
{
  "mcpServers": {
    "pomodoro-ai-mcp": {
      "command": "uvx",
      "args": [
        "pomodoro-ai-mcp"
      ]
    }
  }
}
```

### Cursor (~/.cursor/mcp.json)

```json
{
  "mcpServers": {
    "pomodoro-ai-mcp": {
      "command": "uvx",
      "args": [
        "pomodoro-ai-mcp"
      ]
    }
  }
}
```

### VS Code (.vscode/mcp.json)

```json
{
  "servers": {
    "pomodoro-ai-mcp": {
      "type": "stdio",
      "command": "uvx",
      "args": [
        "pomodoro-ai-mcp"
      ]
    }
  }
}
```

### Windsurf (~/.codeium/windsurf/mcp_config.json)

```json
{
  "mcpServers": {
    "pomodoro-ai-mcp": {
      "command": "uvx",
      "args": [
        "pomodoro-ai-mcp"
      ]
    }
  }
}
```

### Other clients (your client's MCP settings (most use this shape))

```json
{
  "mcpServers": {
    "pomodoro-ai-mcp": {
      "command": "uvx",
      "args": [
        "pomodoro-ai-mcp"
      ]
    }
  }
}
```

## Tools

- `start_session`: Starts a Pomodoro focus session.
- `stop_session`: Stops the current focus session.
- `get_stats`: Returns productivity statistics.

## FAQ

### How do I install it?

The README gives pip install pomodoro_ai_mcp, or npx via Smithery, and shows a claude_desktop_config.json entry that runs it with uvx.

### Is it free?

The repository's source is MIT-licensed and free to self-host. The README does not describe a paid hosted plan for this server.

### Which tools does it expose?

The README examples mention start_session, stop_session and get_stats. It does not list further tools.

### Is Pomodoro Ai MCP free?

Yes. Pomodoro Ai MCP is open source, so you can use and self-host it for free.

### How do I add Pomodoro Ai MCP to Claude Code?

Run this command in your terminal: claude mcp add pomodoro-ai-mcp -- uvx pomodoro-ai-mcp

## Where this comes from

- Description: written from the project's README and its MCP Registry entry.
- Install steps: from the official MCP Registry entry.

## Alternatives

- [Timicx MCP by usefulapi](https://ai-powered.com/mcp/timicx-mcp-by-usefulapi): Timicx MCP by usefulapi is a freemium MCP server for time tracking.

---
Source: https://ai-powered.com/mcp/pomodoro-ai-mcp
