danngalann/zoho-sprints-mcp

Zoho Sprints MCP Server

An MCP (Model Context Protocol) server for Zoho Sprints that provides programmatic access to Zoho Sprints project management functionality. This server enables integration with tools like Claude for automating Zoho Sprints operations.

Features

The server exposes comprehensive tools for managing Zoho Sprints resources:

Projects

• List and fetch project details
• Create new projects
• Update project information
• Retrieve project backlogs

Sprints

• List sprints (upcoming, active, completed, canceled)
• Fetch sprint details
• Create new sprints
• Start, complete, cancel, and reopen sprints
• Manage sprint users
• Update sprint information

Items & Subitems

• Fetch items within sprints
• Create new items and subitems
• Update item details (status, priority, assignee, etc.)
• Move items between sprints/backlogs
• View item activity and comments
• Link items and manage item relationships

Epics

• List and fetch epic details
• Create new epics
• Update epic information
• Associate items with epics
• Move items between epics

Releases

• Manage releases and release cycles
• Create and update releases
• Link items to releases
• Manage release stages

Users & Teams

• Fetch workspace information
• Get workspace settings
• Manage project users
• Add users to sprints

Installation

Prerequisites

• Python 3.12+
• Zoho Sprints account with API access
• Zoho OAuth credentials

Setup

1. Clone or create the project:

cd /path/to/zoho_mcp

2. Install dependencies:

pip install -e .

3. Configure OAuth credentials:

First, get your initial refresh token by running:

python get_refresh_token.py

This script will guide you through the OAuth flow to obtain your refresh token. Follow these steps:

1. Fill in your CLIENT_ID, CLIENT_SECRET, and REDIRECT_URI from your Zoho Developer Console

2. Run the script and click the generated authorization URL

3. Accept the permissions in your browser

4. Copy the authorization code from the redirected URL

5. Paste it back into the script

6. Save the refresh token that's displayed

7. Create a .env file in the project root with your credentials:

ZOHO_CLIENT_ID=your_client_id_here
ZOHO_CLIENT_SECRET=your_client_secret_here
ZOHO_REDIRECT_URI=your_redirect_uri_here
ZOHO_REFRESH_TOKEN=your_refresh_token_here
ZOHO_API_DOMAIN=https://sprintsapi.zoho.eu
ZOHO_ACCOUNTS_URL=https://accounts.zoho.eu
ZOHO_TEAM_ID=your_team_id_here

Running the Server

Start the MCP server:

python server.py

The server will run on the default HTTP transport and be ready to accept MCP protocol requests.

Architecture

Core Components

• server.py - Entry point that initializes and runs the MCP server
• mcp_instance.py - Configures the MCP instance
• settings.py - Manages environment configuration via Pydantic
• zoho_api/ - Main API client modules
  • base_client.py - Base HTTP client with OAuth token management and automatic refresh
  • projects.py - Project management tools
  • sprints.py - Sprint management tools
  • items.py - Work item management tools
  • epics.py - Epic management tools
  • releases.py - Release management tools
  • users.py - User and team management tools
  • workspaces.py - Workspace configuration tools
  • responses/ - Pydantic response models

Authentication

The client uses OAuth 2.0 with automatic token refresh:

• Tokens are refreshed automatically when expired
• A 5-minute buffer is maintained before expiration to prevent request failures
• Failed authentication (401) triggers a single automatic retry with token refresh

API Scopes

The following Zoho Sprints API scopes are required for full functionality:

• ZohoSprints.projects.READ - Read project information
• ZohoSprints.projects.CREATE - Create new projects
• ZohoSprints.projects.UPDATE - Update project details
• ZohoSprints.projects.DELETE - Delete projects
• ZohoSprints.sprints.READ - Read sprint information
• ZohoSprints.sprints.CREATE - Create new sprints
• ZohoSprints.sprints.UPDATE - Update sprint details
• ZohoSprints.sprints.DELETE - Delete sprints
• ZohoSprints.items.READ - Read work items
• ZohoSprints.items.CREATE - Create new items
• ZohoSprints.items.UPDATE - Update item details
• ZohoSprints.items.DELETE - Delete items
• ZohoSprints.epic.READ - Read epic information
• ZohoSprints.epic.CREATE - Create new epics
• ZohoSprints.epic.UPDATE - Update epic details
• ZohoSprints.epic.DELETE - Delete epics
• ZohoSprints.release.READ - Read release information
• ZohoSprints.release.CREATE - Create new releases
• ZohoSprints.release.UPDATE - Update release details
• ZohoSprints.release.DELETE - Delete releases
• ZohoSprints.projectusers.READ - Read project users
• ZohoSprints.projectusers.CREATE - Add project users
• ZohoSprints.projectusers.DELETE - Remove project users
• ZohoSprints.teams.READ - Read workspace/team information

Environment Variables

Troubleshooting

Authentication Issues

• Ensure your OAuth credentials are correct and in the .env file
• Verify the refresh token hasn't been revoked in your Zoho account settings
• Check that the redirect URI matches exactly what's configured in your Zoho Developer Console

API Errors

• Check that your account has the necessary API scopes enabled
• Ensure the ZOHO_TEAM_ID is correct if using a non-default workspace
• Verify that resource IDs (project_id, sprint_id, etc.) are valid

Token Expiration

• The client handles token refresh automatically, but ensure your refresh token is valid
• If you see persistent 401 errors, regenerate your refresh token using get_refresh_token.py

Zoho Developer Resources

• Zoho Sprints API Documentation
• Zoho Developer Console
• OAuth 2.0 Guide