zoho-sprints-mcp

An MCP (Model Context Protocol) server that wraps the Zoho Sprints REST API v1, built with 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

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

Related MCP server: Jira MCP 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 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 below:

   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

   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

   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):

   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.

1. Go to 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:

   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):

{
  "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