Skip to content
Ken Salter edited this page Jul 27, 2026 · 3 revisions

zoho-mcp Wiki

An MCP server that exposes Zoho Mail, Calendar, Contacts, Tasks, Notes, Bookmarks, Groups, and Resource Booking as tools to any MCP-compatible LLM client. 40 tools, local stdio transport, single-user, sending disabled by default.

The README is the reference — what the tools do, what the config variables mean, how the pieces fit. This wiki is the other half: the things you only find out by installing it somewhere. Host quirks, platform-specific setup, error messages and what actually caused them, and the workarounds that don't belong in the README because they're about your machine rather than about this project.

Start here

Two ways to install, and they fail in completely different ways.

Claude Desktop extension (.mcpb) From a checkout
Get it Download from Releases, or npx @anthropic-ai/mcpb pack git clone, then uv run zoho-mcp-setup
Credentials Extension settings form .env file
Authorize The authenticate tool, from inside a conversation uv run zoho-mcp-setup, in a browser
Best for Claude Desktop users who want it to just work Any other MCP client; development; read-only setups

Both paths need uv on your PATH. Neither needs you to install Python — uv brings its own. Both need an application registered in the Zoho API Console with redirect URI http://localhost:8765/callback.

The three things that bite people first

The extension installs disabled, and filling in the settings does not enable it. Because it has required configuration, Claude Desktop installs it switched off and logs has missing required configuration, not enabling automatically. You have to flip the toggle yourself. There's no error to see — the server simply never starts, its tools never appear, and questions about your mail get quietly answered by some other connector.

On Linux you need a keyring backend. The refresh token lives in the OS credential store. Headless servers, minimal desktops, WSL and containers frequently have no Secret Service backend at all, so install gnome-keyring, KWallet, or the keyrings.alt package first. The server will still start without one and report itself unauthenticated — but authenticate can't save its result, so you'll re-authorize forever. macOS and Windows always have a backend.

Two clients means two server processes. Each MCP client launches its own copy. Authorizing in one used to leave the other refusing every call until restarted; that's fixed now, but it's still the right mental model when something works in one client and not another.

Pages

Possible future pages (click to create!)

Before you open an issue

Most reports so far have turned out to be one of the above. Quick checks:

  1. Is the server actually running? In Claude Desktop, is the extension enabled, not just installed?
  2. uv --version — does uv resolve on the PATH the client sees, which isn't always your shell's?
  3. Does uv run zoho-mcp start cleanly from a checkout?
  4. Do the tools appear in the client's tool list at all? If not, it's a launch problem, not a Zoho problem.
  5. Scope errors on write tools usually mean the token was granted before you added the scope. Re-run zoho-mcp-setup, or call authenticate again — a stored token carries only the scopes it was granted.

Still stuck: open an issue with your OS, client, install method, and how the server was launched.

Security issues go privately, not into an issue or a wiki page. This server holds a token that can read and write a real mailbox.

A note on sending email

send_email refuses unless the operator sets ZOHO_ALLOW_AUTO_SEND=true as an environment variable, by hand. It's deliberately not a checkbox in the extension's settings form — a labelled toggle is a much smaller act than editing a server's environment, and the friction is the point. There is no send-a-reply tool at any setting: replies quote incoming mail, incoming mail is untrusted input, and replies always stop at Drafts.

If a wiki page ever tells you to turn sending on to fix something, that page is wrong.

Editing this wiki

Anyone with a GitHub account can edit. A few conventions:

  • Say what you verified, and on what. "Worked on Windows 11, Claude Desktop 0.x, uv 0.5.x" is worth ten times "should work."
  • Paste real error text. People search for the string they're looking at.
  • Never paste a client secret, refresh token, or your real Zoho address. Redact to xxx, and use obviously-fake values in examples the way the test fixtures do.
  • Behavior of the code itself belongs in the repo, not here. If you find a bug, or something the README gets wrong, open an issue or a PR — a wiki page describing a workaround for a fixable bug just outlives the bug.
  • Zoho's own API quirks are already catalogued in docs/zoho-api-notes.md. Add there, not here.

Clone this wiki locally