ZOHO MCP Server
A Model Context Protocol (MCP) server for interrogating and setting up metadata in ZOHO services.
Features
- Connect to various ZOHO services (CRM, Books, Desk, etc.)
- Query and retrieve metadata from ZOHO services
- Set up and configure metadata in ZOHO services
- Provide tools for ZOHO service management through MCP protocol
Installation
Quick Start (recommended)
Clone the repository and install dependencies:```bash
git clone <repository-url>
cd zoho_mcp
uv sync
uv pip install -e .
This will:
1. Install all required dependencies from `pyproject.toml`
2. Install the `zoho_mcp_server` package in development mode
### Manual Installation with uv
If you want to install manually:```bash
uv add "mcp[cli]>=1.1.0" httpx pydantic python-dotenv
uv pip install -e .
Using pip with virtual environment```bash
python -m venv .venv
source .venv/bin/activate # On Windows: .venv\Scripts\activate
pip install -e .
## Configuration
### Step 1: Get ZOHO API Credentials
To use this server, you need to create a ZOHO OAuth application:
1. Go to ZOHO API Console
2. Create a new "Server-based Application"
3. Note your `Client ID` and `Client Secret`
4. Generate a `Refresh Token` using the OAuth flow (see ZOHO documentation)
### Step 2: Configure Environment Variables
Create a `.env` file in the project root with your ZOHO credentials:```env
ZOHO_CLIENT_ID=your_client_id
ZOHO_CLIENT_SECRET=your_client_secret
ZOHO_REFRESH_TOKEN=your_refresh_token
ZOHO_REGION=com # or eu, in, au, jp, ca depending on your region
You can copy .env.example as a starting point:```bash
cp .env.example .env
Then edit .env with your actual credentials
## Usage
### Development Mode
Test the server with MCP Inspector:```bash
uv run mcp dev src/zoho_mcp_server/server.py
Claude Desktop Integration
Add the server to your Claude Desktop configuration. Edit your claude_desktop_config.json:
macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
Windows: %APPDATA%\Claude\claude_desktop_config.json
Linux: ~/.config/Claude/claude_desktop_config.json
Add this to the mcpServers section:```json
{
"mcpServers": {
"ZOHO MCP Server": {
"command": "/absolute/path/to/zoho_mcp/.venv/bin/python",
"args": [
"-m",
"zoho_mcp_server"
]
}
}
}
**Important**:
- Replace `/absolute/path/to/zoho_mcp/` with the actual path to your project directory
- On Windows, use the full path to `.venv\Scripts\python.exe`
- After updating the config, restart Claude Desktop for changes to take effect
### Direct Execution
Run the server directly:```bash
uv run zoho-mcp-server
Available Tools
list_zoho_services: List available ZOHO servicesget_service_modules: Get available modules for a specific ZOHO service (e.g., CRM, Books, Desk)get_module_fields: Get field metadata for a specific module in a ZOHO servicesearch_records: Search for records in a ZOHO module with optional criteria and paginationcreate_record: Create a new record in a ZOHO moduleupdate_record: Update an existing record in a ZOHO module
Available Resources
zoho://services: List of available ZOHO serviceszoho://service/{service}/modules: Available modules in a specific servicezoho://service/{service}/module/{module}/fields: Field metadata for a specific module
Available Prompts
zoho_query_prompt: Generate helpful prompts for ZOHO operations (search, create, update)
Examples
Once the server is running, you can use it through Claude Desktop or any MCP client:
List available ZOHO services:```
Use the list_zoho_services tool
**Get modules for CRM:**```
Use get_service_modules with service="crm"
Get fields for Leads module:```
Use get_module_fields with service="crm" and module="Leads"
**Search for leads:**```
Use search_records with service="crm", module="Leads", criteria="(Email:equals:test@example.com)"
Create a new lead:```
Use create_record with service="crm", module="Leads", and record_data containing the lead fields
## Supported ZOHO Services
The server provides access to these ZOHO services:
- CRM (Customer Relationship Management)
- Books (Accounting)
- Desk (Customer Support)
- People (HR Management)
- Inventory (Inventory Management)
- Subscriptions (Subscription Billing)
- Campaigns (Email Marketing)
- Survey (Online Surveys)
- Projects (Project Management)
## Development
### Project Structure```
zoho_mcp/
├── src/
│ └── zoho_mcp_server/
│ ├── __init__.py
│ ├── __main__.py # Entry point
│ ├── server.py # MCP server implementation
│ ├── config.py # Configuration settings
│ └── zoho_client.py # ZOHO API client
├── .env.example # Example environment variables
├── pyproject.toml # Project dependencies
└── README.md
Running Tests```bash
uv run pytest
### Code Quality```bash
uv run ruff check
uv run mypy src/
Troubleshooting
Missing Dependencies Error
If you see ModuleNotFoundError: No module named 'mcp', run:```bash
uv sync
### Authentication Errors
#### Invalid or Expired Refresh Token
If you see `Failed to refresh access token - invalid_code`, your refresh token is invalid or expired.
**How to fix:**
1. **Go to ZOHO API Console** based on your region:
- EU: https://api-console.zoho.eu/
- US: https://api-console.zoho.com/
- India: https://api-console.zoho.in/
- Australia: https://api-console.zoho.com.au/
- Japan: https://api-console.zoho.jp/
- Canada: https://api-console.zoho.ca/
2. **Navigate to your Server-based Application**:
- Click on your existing application or create a new one
- Go to the "Generate Code" tab (or "Self Client" tab)
3. **Generate a new Refresh Token**:
- Select the required scopes (e.g., `ZohoCRM.modules.ALL`, `ZohoCRM.settings.ALL`)
- Set the time duration (choose appropriate expiration)
- Click "Generate"
- Copy the generated code
4. **Generate Refresh Token from Code**:
- Use the provided code to generate a refresh token
- You can use the ZOHO API Console's built-in tool or make a POST request:```bash
curl -X POST "https://accounts.zoho.eu/oauth/v2/token" \
-d "code=YOUR_GENERATED_CODE" \
-d "client_id=YOUR_CLIENT_ID" \
-d "client_secret=YOUR_CLIENT_SECRET" \
-d "grant_type=authorization_code"
```
5. **Update your `.env` file**:```env
ZOHO_REFRESH_TOKEN=your_new_refresh_token_here
```
6. **Restart the server**
#### Wrong Region Configuration
- Verify your `.env` file has the correct credentials
- Check that you're using the correct region (com, eu, in, au, jp, ca)
- The region in your `.env` must match where your ZOHO account is registered
#### Missing Credentials
If you see errors about missing credentials:
- Ensure `ZOHO_CLIENT_ID`, `ZOHO_CLIENT_SECRET`, and `ZOHO_REFRESH_TOKEN` are all set in `.env`
- Check that there are no extra spaces or quotes around the values
### Module Import Errors
If you see `ModuleNotFoundError: No module named 'zoho_mcp_server'`:
1. **Make sure the package is installed**:```bash
uv pip install -e .
```
2. **Use the correct entry point**:```bash
# ✅ Correct - using installed module
python -m zoho_mcp_server
# or
.venv/bin/python -m zoho_mcp_server
# ❌ Wrong - running file directly will fail with import errors
python src/zoho_mcp_server/server.py
```
3. **For Claude Desktop**, ensure your config uses the virtual environment's Python:```json
{
"command": "/absolute/path/to/zoho_mcp/.venv/bin/python",
"args": ["-m", "zoho_mcp_server"]
}
```
### Debugging Token Issues
To see detailed logs when troubleshooting token issues, you can enable debug logging by setting the log level:```bash
# In your terminal before running the server
export LOG_LEVEL=DEBUG
uv run zoho-mcp-server
This will show detailed information about the token refresh process, including the exact API requests and responses.
Contributing
Contributions are welcome! Please feel free to submit a Pull Request.
License
MIT License
