laravel-zoho/mcp-server

Laravel package that runs a Model Context Protocol (MCP) server exposing Zoho REST API operations as MCP tools (via Laravel MCP).

dev-main 2026-05-07 08:08 UTC

Requires

• php: ^8.3
• guzzlehttp/guzzle: ^7.8
• illuminate/auth: ^13.0
• illuminate/console: ^13.0
• illuminate/contracts: ^13.0
• illuminate/database: ^13.0
• illuminate/http: ^13.0
• illuminate/routing: ^13.0
• illuminate/support: ^13.0
• laravel/mcp: ^0.7

Requires (Dev)

• orchestra/testbench: ^11.0
• phpunit/phpunit: ^11.5.50|^12.0

MIT

• oauth
• laravel
• Zoho
• mcp
• ZOHO-CRM
• model-context-protocol

README

Laravel package that exposes Zoho REST APIs to AI clients through the Model Context Protocol, using Laravel’s first-party Laravel MCP package (laravel/mcp) — not a separate low-level MCP SDK.

Requirements

• PHP 8.3+
• Laravel 13+ (this release aligns with laravel/mcp and Illuminate 13 components)
• A Zoho OAuth client (client id + secret) in Zoho API Console

laravel/mcp is a direct dependency; installing this package pulls it in and registers the MCP console commands (for example mcp:start).

Installation

composer require laravel-zoho/mcp-server

The service provider loads migrations automatically. Run php artisan migrate in your app.

Publish configuration (optional):

php artisan vendor:publish --tag=zoho-mcp-config

Multi-user OAuth (recommended)

Each Laravel user completes the Zoho authorization code flow in the browser. Tokens are stored in zoho_mcp_oauth_connections (encrypted). Each user then gets an MCP access token (zmcp_…) from POST /zoho-mcp/mcp-access-tokens to pass as ZOHO_MCP_ACCESS_TOKEN.

See config/zoho-mcp.php for ZOHO_OAUTH_CALLBACK_URL, scopes, route prefix, and middleware.

Running the MCP server (local / stdio)

This package registers a local MCP server handle (default zoho, overridable with ZOHO_MCP_LOCAL_HANDLE / config('zoho-mcp.mcp_local_handle')):

php artisan mcp:start zoho

Compatibility wrapper (sets --token for this process, then calls mcp:start):

php artisan zoho:mcp --token='zmcp_....'
# or
export ZOHO_MCP_ACCESS_TOKEN='zmcp_....'
php artisan zoho:mcp

Legacy single-tenant mode still works when ZOHO_REFRESH_TOKEN and client credentials are set and no MCP access token is provided (see BootstrapZohoCredentials).

Cursor example

{
  "mcpServers": {
    "zoho": {
      "command": "php",
      "args": ["/absolute/path/to/your/project/artisan", "mcp:start", "zoho"],
      "cwd": "/absolute/path/to/your/project",
      "env": {
        "ZOHO_MCP_ACCESS_TOKEN": "zmcp_your_personal_token_here"
      }
    }
  }
}

You may use zoho:mcp instead of mcp:start zoho if you prefer the wrapper command.

MCP tools

Tools are implemented as Laravel\Mcp\Server\Tool classes and return Laravel\Mcp\Response::json() (or Response::error() for recoverable issues).

Tool	Description
zoho_api_request	Generic GET / POST / PUT / PATCH / DELETE under the active API base URL.
zoho_crm_list_modules	CRM settings/modules
zoho_crm_get_records	Paginated list
zoho_crm_get_record	Single record
zoho_crm_create_records	Create rows (data array)
zoho_crm_update_records	Update rows (include id)
zoho_crm_delete_records	Delete by ids
zoho_crm_coql_query	Read-only COQL
zoho_crm_search_records	Criteria-based search

Security

• MCP access tokens are secrets; rotate via expiry or DB deletion.
• Zoho refresh tokens in the database are encrypted with your app key.

License

MIT