zoho-mcp

Zoho Sprints MCP Server

A Laravel 12 MCP server that connects Claude AI to Zoho Sprints — manage teams, projects, sprints, tasks, epics, and comments directly from your Claude conversations.

Built with php-mcp/laravel and the Model Context Protocol.

---

Features

• 46 MCP tools covering the full Zoho Sprints API
• Full CRUD for projects, sprints, items (tasks), epics, and comments
• Read access to teams and members, and to a project's statuses, item types and priorities
• Compact item listing that decodes Zoho's positional rows and drops the HTML descriptions — ~85% smaller, so a whole sprint fits comfortably in context
• Automatic OAuth 2.0 token management with silent refresh
• Works with Claude Code (stdio) and Claude Desktop (HTTP)

Tools

Category	Tools
Teams	zoho_list_teams, zoho_list_team_members
Projects	zoho_list_projects, zoho_get_project, zoho_create_project, zoho_update_project, zoho_delete_project, zoho_list_project_members
Sprints	zoho_list_sprints, zoho_get_sprint, zoho_create_sprint, zoho_update_sprint, zoho_delete_sprint
Items	zoho_list_items, zoho_get_item, zoho_create_item, zoho_update_item, zoho_delete_item
Epics	zoho_list_epics, zoho_get_epic, zoho_create_epic, zoho_update_epic, zoho_delete_epic
Comments	zoho_list_comments, zoho_add_comment, zoho_update_comment, zoho_delete_comment
Workflow	zoho_list_item_statuses, zoho_list_item_types, zoho_list_priorities
Identity	zoho_whoami

A few things worth knowing:

• Ids, not names. Items carry statuses, types and priorities as opaque ids. The Workflow tools resolve those ids to names — and give you the id to pass back to zoho_update_item to move an item to, say, In progress.
• zoho_list_items accepts compact: true. Zoho returns each item as a positional array plus a *_prop name→index map, with the full HTML description inline. Compact mode decodes the rows, resolves owner ids to names, and drops the descriptions — a real sprint goes from ~30,000 to ~4,300 characters. Fetch the description for the one item you care about with zoho_get_item.
• zoho_whoami answers "which account is this server acting as", and with a team_id resolves that account to its Sprints zsUserId — the value items carry as ownerId, so an agent can tell which items are yours. It needs the AaaServer.profile.READ scope; if you authorised before this tool existed, re-run the OAuth step at /zoho/auth.

---

Requirements

• PHP 8.3+ — php.net/downloads or via your package manager
• Composer — getcomposer.org/download (the install script handles this automatically)
• Git
• A Zoho Sprints account with API access enabled
• A Zoho OAuth app registered at api-console.zoho.com → Server-based Applications

---

Installation

Claude Code plugin (recommended)

In the Claude Code CLI, run:

/plugin marketplace add idoko-emmanuel/zoho-mcp
/plugin install zoho-mcp@idoko-emmanuel

In VS Code, open this link (paste it into your browser's address bar):

vscode://anthropic.claude-code/install-plugin?plugin=zoho-mcp&marketplace=idoko-emmanuel/zoho-mcp

Or type /plugins in the Claude Code panel, add idoko-emmanuel/zoho-mcp on the Marketplaces tab, then install zoho-mcp from the Plugins tab.

Claude Code asks for your Zoho Client ID, Client Secret and data centre (see Register your OAuth app). To change them later, run /plugin (/plugins in VS Code), open zoho-mcp and choose Configure.

Connect your Zoho account: start a new session. Until Zoho is authorised, the plugin runs a small local auth server and shows you a link:

Zoho Sprints isn't connected yet. Open http://localhost:8000/zoho/auth to authorise it (one time only).

Open it, approve access in Zoho, and you're done: no restart needed. The auth server stops by itself once the token is saved (or after 30 minutes). Then try "List all my Zoho Sprints teams". If the link doesn't load, or you need to re-authorise later, run /zoho-mcp:connect and Claude walks you through it.

Requirements: PHP 8.3+ and bash on your PATH (on Windows, Git Bash or WSL), and port 8000 free while you authorise. Composer is downloaded automatically if you don't have it.

How it works: the first session runs composer install and sets up the app, which takes 2 to 3 minutes, so Claude's first reply waits for it. If the sprints server shows as failed in /mcp during that first run, reconnect it once setup finishes. The app, its SQLite database and your OAuth tokens live in ~/.claude/plugins/data/zoho-mcp-idoko-emmanuel/, so they survive plugin updates. Setup logs go to setup.log in that folder.

Where your secret is stored: Claude Code keeps the Client Secret in your system's secure credential store. The plugin also writes it to the app's .env file in the folder above (readable only by your user), because the local auth server needs it to complete the OAuth step.

Already installed with install.sh? Remove the old registration so the tools don't appear twice: claude mcp remove zoho-sprints --scope user

macOS / Linux — One-line install

The install script checks for PHP 8.3+, installs Composer if missing, clones the repo, sets up the database, prompts for your Zoho credentials, and registers the MCP server with Claude Code automatically.

curl -fsSL https://raw.githubusercontent.com/idoko-emmanuel/zoho-mcp/main/install.sh | bash

After the script completes, follow the on-screen instructions to complete the OAuth flow (one-time browser step).

Windows

The install script uses Unix shell syntax and won't run in PowerShell or Command Prompt. Use one of these approaches instead.

Note: If you run curl -fsSL ... in PowerShell you'll get an error because PowerShell's built-in curl is an alias for Invoke-WebRequest and doesn't accept Unix curl flags (-f, -s, -S, -L).

Option A — WSL or Git Bash (recommended)

If you have WSL or Git for Windows installed, open a WSL or Git Bash terminal and run the same one-liner:

curl -fsSL https://raw.githubusercontent.com/idoko-emmanuel/zoho-mcp/main/install.sh | bash

Option B — Manual install (PowerShell)

git clone https://github.com/idoko-emmanuel/zoho-mcp.git "$env:LOCALAPPDATA\zoho-mcp"
cd "$env:LOCALAPPDATA\zoho-mcp"
copy .env.example .env
composer install --no-dev --no-interaction --no-scripts
php artisan key:generate --force
php artisan migrate --force

Then edit .env to add your Zoho credentials (see Configure Zoho credentials below), and register the MCP server:

claude mcp add --scope user zoho-sprints -- php "$env:LOCALAPPDATA\zoho-mcp\artisan" mcp:serve

For Claude Desktop, add to %APPDATA%\Claude\claude_desktop_config.json:

{
  "mcpServers": {
    "zoho-sprints": {
      "command": "php",
      "args": ["C:\\Users\\YourName\\AppData\\Local\\zoho-mcp\\artisan", "mcp:serve"]
    }
  }
}

Manual install (macOS / Linux)

If you prefer to run each step yourself:

1. Install Composer (skip if already installed)

php -r "copy('https://getcomposer.org/installer', 'composer-setup.php');"
php composer-setup.php && rm composer-setup.php
sudo mv composer.phar /usr/local/bin/composer

2. Clone and set up

git clone https://github.com/idoko-emmanuel/zoho-mcp.git ~/.local/share/zoho-mcp
cd ~/.local/share/zoho-mcp
composer install --no-dev
cp .env.example .env
php artisan key:generate
php artisan migrate

3. Configure Zoho credentials

Edit .env and fill in your Zoho OAuth credentials:

ZOHO_CLIENT_ID=your-client-id
ZOHO_CLIENT_SECRET=your-client-secret
ZOHO_REDIRECT_URI=http://localhost:8000/zoho/callback

# Change to .eu / .in / .com.au if your Zoho account is in another region
ZOHO_ACCOUNTS_URL=https://accounts.zoho.com
ZOHO_SPRINTS_URL=https://sprintsapi.zoho.com/zsapi

4. Register with Claude Code

claude mcp add --scope user zoho-sprints -- php ~/.local/share/zoho-mcp/artisan mcp:serve

Or for Claude Desktop, add to ~/Library/Application Support/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "zoho-sprints": {
      "command": "php",
      "args": ["/Users/you/.local/share/zoho-mcp/artisan", "mcp:serve"]
    }
  }
}

---

Uninstallation

macOS / Linux:

curl -fsSL https://raw.githubusercontent.com/idoko-emmanuel/zoho-mcp/main/uninstall.sh | bash

Windows (PowerShell):

claude mcp remove zoho-sprints --scope user
Remove-Item -Recurse -Force "$env:LOCALAPPDATA\zoho-mcp"

This will:

• Remove the MCP server registration from Claude Code
• Remove the app directory (~/.local/share/zoho-mcp on macOS/Linux, %LOCALAPPDATA%\zoho-mcp on Windows)

---

Zoho OAuth setup

1. Register your OAuth app

Go to api-console.zoho.com and create a Server-based Application. Set the redirect URI to:

http://localhost:8000/zoho/callback

Copy your Client ID and Client Secret — you'll need them during install (or to edit .env manually).

2. Enable API access in Zoho Sprints

Go to Zoho Sprints → Settings → API and enable API access for your team.

3. Authorise (one-time)

Start the local server and complete the OAuth flow in your browser:

php ~/.local/share/zoho-mcp/artisan serve

Then open: http://localhost:8000/zoho/auth

Zoho will ask you to grant permissions. After approval you'll be redirected back and the tokens are saved automatically. You can stop the server once authorised — the MCP server runs via stdio and doesn't need a persistent HTTP server.

---

Usage examples

Once connected, start a new Claude Code session and try:

• "List all my Zoho Sprints teams"
• "Show me all projects in my team"
• "Create a new sprint called 'Sprint 5' in project X starting next Monday"
• "Show me all open items in the current sprint"
• "Add a comment to task #123: 'Ready for review'"
• "Move item X to done and assign it to John"

---

Running tests

php artisan test

---

Project structure

app/
├── Http/Controllers/
│   └── ZohoAuthController.php   # OAuth redirect + callback
├── Mcp/Tools/
│   ├── TeamTools.php            # Team & member tools
│   ├── ProjectTools.php         # Project CRUD tools
│   ├── SprintTools.php          # Sprint CRUD tools
│   ├── ItemTools.php            # Task/item CRUD tools
│   ├── EpicTools.php            # Epic CRUD tools
│   └── CommentTools.php         # Comment CRUD tools
├── Models/
│   └── ZohoToken.php            # OAuth token model
└── Services/
    ├── ZohoAuthService.php      # OAuth flow & token refresh
    └── ZohoSprintsService.php   # Zoho Sprints HTTP client
config/
├── mcp.php                      # MCP server configuration
└── zoho.php                     # Zoho API configuration

---

Contributing

1. Create a feature branch from main:

   git checkout main
   git pull
   git checkout -b feat/your-feature-name
   

2. Make your changes and commit them.

3. Push your branch and open a pull request against main:

   git push -u origin feat/your-feature-name
   

4. Ensure CI checks pass before requesting a review.

---

License

MIT