Zoho Projects MCP Server
Provides comprehensive integration with Zoho Projects API for managing projects, tasks, issues, milestones, phases, users, and search functionality across portals and projects
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@Zoho Projects MCP Server list all open tasks in the 'Website Redesign' project"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
Zoho Projects MCP Server
A Model Context Protocol (MCP) server that provides integration with Zoho Projects API. This server enables AI assistants to interact with Zoho Projects for managing projects, tasks, issues, milestones, and more.
Features
Supported Operations
Portal Management
List all portals
Get portal details
Project Management
List projects
Get project details
Create new projects
Update existing projects
Delete projects (move to trash)
Task Management
List tasks (portal or project level)
Get task details
Create tasks
Update tasks
Delete tasks
Issue Management
List issues (portal or project level)
Get issue details
Create issues
Update issues
Phase/Milestone Management
List phases
Create phases
Search
Search across portal or project
Filter by module (projects, tasks, issues, milestones, forums, events)
User Management
List users in portal or project
Related MCP server: ProjectHub MCP Server
Prerequisites
Node.js (v18 or higher)
Zoho Projects Account with API access
Zoho OAuth Credentials
Setup
1. Get Zoho OAuth Credentials (Detailed Guide)
Step 1: Create a Zoho Developer Application
Go to Zoho API Console
Click "Add Client" button
Choose "Self Client" (recommended for personal use) or "Server-based Applications"
Fill in the application details:
Client Name: e.g., "Zoho Projects MCP"
Homepage URL: Your website or
http://localhostfor testingAuthorized Redirect URIs:
http://localhost:8080/callback(or your preferred redirect URL)
Click "Create" and note down:
Client ID (e.g.,
1000.XXXXXXXXXX)Client Secret (keep this secure!)
Step 2: Generate Authorization Code
Build the authorization URL with required scopes:
https://accounts.zoho.{REGION}/oauth/v2/auth? scope=ZohoProjects.portals.ALL,ZohoProjects.projects.ALL,ZohoProjects.tasks.ALL,ZohoProjects.bugs.ALL,ZohoProjects.milestones.ALL,ZohoProjects.users.READ,ZohoSearch.securesearch.READ &client_id=YOUR_CLIENT_ID &response_type=code &access_type=offline &redirect_uri=YOUR_REDIRECT_URIReplace
{REGION}with your region:US:
comEU:
euIN:
inAU:
com.auCN:
com.cn
Open this URL in your browser
Log in to your Zoho account and authorize the application
You'll be redirected to your redirect URI with a code parameter in the URL:
http://localhost:8080/callback?code=1000.XXXXX.XXXXX&location=in&accounts-server=https://accounts.zoho.inCopy the
codevalue (valid for ~2 minutes, use it immediately!)
Step 3: Exchange Code for Tokens
Use this curl command to get your access and refresh tokens:
curl -X POST https://accounts.zoho.{REGION}/oauth/v2/token \
-d "code=YOUR_AUTHORIZATION_CODE" \
-d "client_id=YOUR_CLIENT_ID" \
-d "client_secret=YOUR_CLIENT_SECRET" \
-d "redirect_uri=YOUR_REDIRECT_URI" \
-d "grant_type=authorization_code"Response will contain:
{
"access_token": "1000.xxxx.yyyy",
"refresh_token": "1000.zzzz.aaaa",
"expires_in": 3600,
"api_domain": "https://www.zohoapis.in",
"token_type": "Bearer"
}Important: Save both tokens:
access_token: Valid for 1 hour (auto-refreshed by the server)
refresh_token: Long-lived, used to get new access tokens
Step 4: Find Your Portal ID
Method 1: From URL
Go to your Zoho Projects in browser
Look at the URL:
https://projects.zoho.{REGION}/portal/{PORTAL_ID}/...The number after
/portal/is your Portal ID (e.g.,60028147039)
Method 2: Using API
curl -X GET https://projectsapi.zoho.{REGION}/api/v3/portals \
-H "Authorization: Zoho-oauthtoken YOUR_ACCESS_TOKEN"Response will list all your portals with their IDs.
Step 5: Verify Credentials
Test your setup with this API call:
curl -X GET https://projectsapi.zoho.{REGION}/api/v3/portal/YOUR_PORTAL_ID/projects \
-H "Authorization: Zoho-oauthtoken YOUR_ACCESS_TOKEN"Expected: JSON response with your projects list If error: Check token, portal ID, and API domain match your region
Required Scopes Summary
Make sure your OAuth token has these scopes:
✅
ZohoProjects.portals.ALL- Portal operations✅
ZohoProjects.projects.ALL- Project management✅
ZohoProjects.tasks.ALL- Task management✅
ZohoProjects.bugs.ALL- Issue/bug management✅
ZohoProjects.milestones.ALL- Milestone/phase management✅
ZohoProjects.users.READ- User information✅
ZohoSearch.securesearch.READ- Search functionality
2. Setup and Installation
Node.js Setup
Prerequisites:
Node.js (v18 or higher)
Steps:
Clone and install:
git clone <repository-url>
cd zoho-mcp
npm install
npm run buildCreate
.envfile with your credentials (see Configuration section below)Run the server:
# Stdio server (for local MCP clients)
npm start
# HTTP server (for remote access)
npm run start:http3. Configuration
Create a .env file in the project root with the following variables:
# OAuth credentials (required)
ZOHO_ACCESS_TOKEN=your_access_token_here
ZOHO_REFRESH_TOKEN=your_refresh_token_here
ZOHO_CLIENT_ID=your_client_id_here
ZOHO_CLIENT_SECRET=your_client_secret_here
# Portal configuration (required)
ZOHO_PORTAL_ID=your_portal_id_here
# API domain (optional, choose based on your region)
ZOHO_API_DOMAIN=https://projectsapi.zoho.com
ZOHO_ACCOUNTS_DOMAIN=https://accounts.zoho.com
# HTTP Server configuration (optional, for remote access)
HTTP_PORT=3001
ALLOWED_ORIGINS=http://localhost:3000
ALLOWED_HOSTS=127.0.0.1,localhostRegion-specific domains:
US:
projectsapi.zoho.com/accounts.zoho.comEU:
projectsapi.zoho.eu/accounts.zoho.euIN:
projectsapi.zoho.in/accounts.zoho.inAU:
projectsapi.zoho.com.au/accounts.zoho.com.auCN:
projectsapi.zoho.com.cn/accounts.zoho.com.cn
4. Configure Claude Desktop
Add to your Claude Desktop configuration file:
macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
Windows: %APPDATA%\Claude\claude_desktop_config.json
For Node.js Setup:
{
"mcpServers": {
"zoho-projects": {
"command": "node",
"args": ["/absolute/path/to/zoho-mcp/dist/index.js"],
"env": {
"ZOHO_ACCESS_TOKEN": "your_access_token_here",
"ZOHO_REFRESH_TOKEN": "your_refresh_token_here",
"ZOHO_CLIENT_ID": "your_client_id_here",
"ZOHO_CLIENT_SECRET": "your_client_secret_here",
"ZOHO_PORTAL_ID": "your_portal_id_here",
"ZOHO_API_DOMAIN": "https://projectsapi.zoho.in",
"ZOHO_ACCOUNTS_DOMAIN": "https://accounts.zoho.in"
}
}
}
}Usage Examples
Once configured, you can use Claude to interact with Zoho Projects:
List Projects
Can you list all my Zoho Projects?Create a New Project
Create a new project called "Website Redesign" with description "Redesign company website" starting on 2025-01-15 and ending on 2025-03-31List Tasks
Show me all tasks in project ID 1234567890Create a Task
Create a high priority task called "Design homepage mockup" in project 1234567890, due on 2025-02-15Search
Search for "bug fix" in all modulesList Issues
Show me all issues in project 1234567890Project Structure
zoho-projects-mcp-server/
├── src/
│ └── index.ts # Main server implementation
├── dist/ # Compiled JavaScript (generated)
├── package.json
├── tsconfig.json
└── README.mdAvailable Tools
The server provides the following MCP tools:
list_portals- Get all portalsget_portal- Get portal detailslist_projects- List all projectsget_project- Get project detailscreate_project- Create a new projectupdate_project- Update a projectdelete_project- Delete a projectlist_tasks- List tasksget_task- Get task detailscreate_task- Create a taskupdate_task- Update a taskdelete_task- Delete a tasklist_issues- List issuesget_issue- Get issue detailscreate_issue- Create an issueupdate_issue- Update an issuelist_phases- List phases/milestonescreate_phase- Create a phasesearch- Search portal or projectlist_users- List users
Troubleshooting
Authentication Issues
Ensure your access token is valid and not expired
Verify the token has the required scopes
Check that the portal ID is correct
API Errors
Check the Zoho API documentation for rate limits
Ensure you're using the correct API domain for your region
Verify that the user has appropriate permissions
Connection Issues
Restart Claude Desktop after configuration changes
Check the Claude Desktop logs for error messages
Verify the server path in the configuration
OAuth Token Management
Token Expiration
Access tokens expire after 1 hour (3600 seconds). This MCP server automatically refreshes tokens using the refresh token.
Manual Token Refresh
If you need to manually refresh your access token:
# For India region (accounts.zoho.in)
curl -X POST https://accounts.zoho.in/oauth/v2/token \
-d "refresh_token=YOUR_REFRESH_TOKEN" \
-d "client_id=YOUR_CLIENT_ID" \
-d "client_secret=YOUR_CLIENT_SECRET" \
-d "grant_type=refresh_token"
# For other regions, use the appropriate accounts domain:
# US: https://accounts.zoho.com/oauth/v2/token
# EU: https://accounts.zoho.eu/oauth/v2/token
# AU: https://accounts.zoho.com.au/oauth/v2/token
# CN: https://accounts.zoho.com.cn/oauth/v2/tokenResponse example:
{
"access_token": "1000.xxx.yyy",
"scope": "ZohoProjects.portals.ALL ZohoProjects.projects.ALL...",
"api_domain": "https://www.zohoapis.in",
"token_type": "Bearer",
"expires_in": 3600
}Automatic Token Refresh
The MCP server automatically handles token refresh. Configure the following environment variables:
ZOHO_REFRESH_TOKEN=your_refresh_token_here
ZOHO_CLIENT_ID=your_client_id_here
ZOHO_CLIENT_SECRET=your_client_secret_here
ZOHO_ACCOUNTS_DOMAIN=https://accounts.zoho.in # Match your regionThe server will automatically refresh the access token before it expires.
API Reference
For detailed API documentation, visit: https://projects.zoho.com/api-docs
License
MIT
Contributing
Contributions are welcome! Please feel free to submit issues or pull requests.
Support
For issues related to:
MCP Server: Open an issue in this repository
Zoho Projects API: Contact Zoho support or check their documentation
Claude Desktop: Check Anthropic's documentation
Available Tools
20 toolscreate_issueD
Create a new issue
Inputs: project_id (required), title (required), description, severity, +1 more.
create_phaseC
Create a new phase/milestone
Inputs: project_id (required), name (required), start_date, end_date, +1 more.
create_projectC
Create a new project
Inputs: name (required), description, start_date, end_date, +1 more.
create_taskC
Create a new task in a project
Inputs: project_id (required), name (required), description, priority, +3 more.
delete_projectA
Delete a project (moves to trash)
Inputs: project_id (required).
delete_taskB
Delete a task
Inputs: project_id (required), task_id (required).
get_issueB
Get details of a specific issue
Inputs: project_id (required), issue_id (required).
get_portalB
Get details of a specific portal
Inputs: portal_id (required).
get_projectA
Get details of a specific project
Inputs: project_id (required).
get_taskC
Get details of a specific task
Inputs: project_id (required), task_id (required).
list_issuesB
List issues from a project or portal
Inputs: project_id, page, per_page.
list_phasesB
List phases/milestones from a project
Inputs: project_id (required), page, per_page.
list_portalsA
Retrieve all Zoho Projects portals
Inputs: no named parameters.
list_projectsB
List all projects in a portal
Inputs: page, per_page.
list_tasksB
List tasks from a project or portal
Inputs: project_id, page, per_page.
list_usersA
List users in a portal or project
Inputs: project_id.
searchC
Search across portal or project
Inputs: search_term (required), project_id, module, page, +1 more.
update_issueD
Update an issue
Inputs: project_id (required), issue_id (required), title, description, +1 more.
update_projectB
Update an existing project
Inputs: project_id (required), name, description, start_date, +2 more.
update_taskC
Update a task
Inputs: project_id (required), task_id (required), name, description, +3 more.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 20 tools
Every tool has a clearly distinct purpose with no ambiguity. Tools are organized by resource (issue, phase, project, task, portal, user) and action (create, get, list, update, delete, search), making it easy for an agent to select the right one. Overlap is minimal, such as list_issues vs. search, but their descriptions clarify distinct use cases.
Tool names follow a highly consistent verb_noun pattern throughout, such as create_issue, get_project, list_tasks, update_task, and delete_project. There are no deviations in naming conventions, making the set predictable and easy to navigate for an agent.
With 20 tools, the count is slightly high but reasonable for a project management domain covering multiple resources like issues, tasks, projects, portals, phases, and users. It feels comprehensive rather than bloated, though it borders on the upper limit of ideal scope.
The tool surface provides complete CRUD/lifecycle coverage for the domain, including create, get, list, update, and delete operations for key resources like issues, tasks, and projects. There are no obvious gaps, and tools like search and list_users add useful functionality, ensuring agents can handle typical workflows without dead ends.
Maintenance
Related MCP Connectors
Manage Loom projects, tasks, bugs, defects, clients and phases from AI assistants
Create and manage MeisterTask projects, tasks, and notes from your AI assistant.
Manage Avaza projects, tasks, timesheets, expenses, invoices, and scheduling from AI assistants.
AI-native project and portfolio management platform for PMOs. OAuth + PAT.
Related MCP Servers
- AlicenseAqualityDmaintenanceEnables AI assistants to interact with Todoist tasks and projects through natural language. Supports comprehensive task management including creating, updating, completing tasks, managing projects, and filtering by various criteria.11GPL 3.0
- AlicenseBqualityCmaintenanceEnables AI assistants to interact with ProjectHub for comprehensive project management through natural language. It provides 25 tools to manage tasks, workspaces, time tracking, notes, and discussions via the ProjectHub API.47MIT
- AlicenseNot gradedqualityBmaintenanceEnables AI assistants to manage Todocko application data, including tasks, projects, worklogs, and attachments. It supports comprehensive project management operations such as tracking activity, managing Kanban boards, and handling shared project synchronization.253 npm1MIT
- FlicenseAqualityDmaintenanceConnects Zoho Projects with Claude AI to manage projects, tasks, time tracking, and comments through natural language conversations.116-