# zoho-sprints-mcp

An MCP (Model Context Protocol) server that wraps the [Zoho Sprints](https://sprints.zoho.com) REST API v1, built with [`fastmcp`](https://github.com/jlowin/fastmcp). It exposes Zoho Sprints projects, sprints, items, statuses, and comments as tools that any MCP-compatible client (Claude Desktop, Claude Code, etc.) can call.

## Tools

| Tool | Description |
| --- | --- |
| `list_projects` | List all projects in the portal |
| `list_sprints(project_id, status="all")` | List sprints for a project |
| `get_sprint(project_id, sprint_id)` | Get a single sprint |
| `list_sprint_items(project_id, sprint_id)` | List items in a sprint |
| `get_item(project_id, sprint_id, item_id)` | Get a single item |
| `create_item(project_id, sprint_id, name, description, assignee_id, priority, item_type_id, story_points)` | Create a new item |
| `update_item_status(project_id, sprint_id, item_id, status_id)` | Update an item's status |
| `update_item(project_id, sprint_id, item_id, fields)` | Update arbitrary fields on an item |
| `list_statuses(project_id)` | List available statuses for a project |
| `get_comments(project_id, sprint_id, item_id)` | List comments on an item |
| `add_comment(project_id, sprint_id, item_id, content)` | Add a comment to an item |

Every tool catches errors internally and returns `{"error": "..."}` instead of raising, so a bad call never crashes the server.

## Quick install as a Claude Code plugin

This repo doubles as a Claude Code plugin — install it and the `zoho-sprints` MCP tools (plus two starter slash commands) are available in any project immediately, no manual venv setup or config editing required. It uses [`uv`](https://docs.astral.sh/uv/) to auto-manage the Python environment.

1. Install `uv` if you don't have it: `curl -LsSf https://astral.sh/uv/install.sh | sh`
2. Export your Zoho credentials in your shell profile (`~/.zshrc`, `~/.bashrc`, etc.) — see [Getting a Zoho OAuth refresh token](#getting-a-zoho-oauth-refresh-token) below:

   ```bash
   export ZOHO_PORTAL_ID=your_portal_id
   export ZOHO_CLIENT_ID=your_client_id
   export ZOHO_CLIENT_SECRET=your_client_secret
   export ZOHO_REFRESH_TOKEN=your_refresh_token
   export ZOHO_TLD=com
   ```

3. In Claude Code, add this repo as a plugin marketplace and install the plugin:

   ```
   /plugin marketplace add egenius01/zoho-sprints-mcp
   /plugin install zoho-sprints
   ```

4. Restart Claude Code (or run `/mcp` to confirm `zoho-sprints` is connected). You now have:
   - All 11 tools (`list_projects`, `create_item`, `add_comment`, etc.) available to Claude automatically.
   - `/zoho-sprints:sprint-status [project_id] [sprint_id]` — summarize a sprint's items by status.
   - `/zoho-sprints:create-item [project_id] [sprint_id] [name]` — create a new item interactively.

Update the plugin later with `/plugin marketplace update zoho-sprints-mcp` then `/plugin update zoho-sprints`.

## Manual setup (venv, no plugin)

1. **Clone and install dependencies**

   ```bash
   git clone https://github.com/<your-username>/zoho-sprints-mcp.git
   cd zoho-sprints-mcp
   python -m venv .venv && source .venv/bin/activate
   pip install -r requirements.txt
   ```

2. **Copy the env template and fill it in**

   ```bash
   cp .env.example .env
   ```

3. **Get a Zoho OAuth refresh token** (see below), and set the following in `.env`:

   ```
   ZOHO_PORTAL_ID=...
   ZOHO_CLIENT_ID=...
   ZOHO_CLIENT_SECRET=...
   ZOHO_REFRESH_TOKEN=...
   ZOHO_TLD=com
   ```

4. **Run it directly to sanity check** (optional — this also runs as part of `server.py`'s startup):

   ```bash
   python server.py
   ```

   You should see no errors; the process will wait on stdio for an MCP client to connect.

## Getting a Zoho OAuth refresh token

Zoho Sprints uses standard Zoho OAuth 2.0. You need a **Self Client** (or server-based app) registered at the [Zoho API Console](https://api-console.zoho.com).

1. Go to [api-console.zoho.com](https://api-console.zoho.com) and sign in with the account that has access to your Sprints portal.
2. Click **Add Client** → **Self Client** (simplest for personal/local use; use **Server-based Applications** if you need a redirect-based flow).
3. Note the **Client ID** and **Client Secret** shown — these are your `ZOHO_CLIENT_ID` and `ZOHO_CLIENT_SECRET`.
4. Go to the **Generate Code** tab for your Self Client.
5. Enter the scope your integration needs, e.g.:

   ```
   ZohoSprints.projects.READ,ZohoSprints.sprints.READ,ZohoSprints.sprints.CREATE,ZohoSprints.sprints.UPDATE
   ```

   (Adjust scopes to match which tools you plan to use — add `.CREATE`/`.UPDATE` scopes for `create_item`, `update_item`, `update_item_status`, and `add_comment`.)

6. Set a time duration (e.g. 10 minutes) and generate the code. Copy the generated **authorization code**.
7. Exchange the authorization code for a refresh token by calling:

   ```bash
   curl -X POST "https://accounts.zoho.com/oauth/v2/token" \
     -d "grant_type=authorization_code" \
     -d "client_id=YOUR_CLIENT_ID" \
     -d "client_secret=YOUR_CLIENT_SECRET" \
     -d "code=YOUR_AUTHORIZATION_CODE"
   ```

   (Swap `zoho.com` for your data center's domain, e.g. `zoho.eu`, `zoho.in`, if applicable — this should match `ZOHO_TLD`.)

8. The response includes a `refresh_token` — this is your `ZOHO_REFRESH_TOKEN`. It does not expire unless revoked, and the server uses it to auto-fetch short-lived access tokens on demand.

9. Your **Portal ID** (`ZOHO_PORTAL_ID`) can be found in your Sprints portal URL, e.g. `https://sprints.zoho.com/portal/<portal-id>/...`, or via the `list_projects`/portal APIs once you have a token.

### Local testing without OAuth

If you just want to test quickly and already have a short-lived access token (e.g. copied from the API console's token playground), you can set `ZOHO_ACCESS_TOKEN` in `.env` instead of the client ID/secret/refresh token trio. This skips the refresh flow entirely but the token will expire (typically after 1 hour).

## Using with Claude Desktop

Add this to your `claude_desktop_config.json` (Settings → Developer → Edit Config):

```json
{
  "mcpServers": {
    "zoho-sprints": {
      "command": "python",
      "args": ["/absolute/path/to/zoho-sprints-mcp/server.py"],
      "env": {
        "ZOHO_PORTAL_ID": "your_portal_id",
        "ZOHO_CLIENT_ID": "your_client_id",
        "ZOHO_CLIENT_SECRET": "your_client_secret",
        "ZOHO_REFRESH_TOKEN": "your_refresh_token",
        "ZOHO_TLD": "com"
      }
    }
  }
}
```

Restart Claude Desktop after saving. The `zoho-sprints` tools should appear in the tool picker.

## License

MIT