MCP Vtenext

What Castaldo-Solutions/mcp-vtenext MCP server does

Castaldo-Solutions/mcp-vtenext MCP server gives MCP-compatible clients access to selected VTENext CRM operations. VTENext is an open-source CRM based on vtiger, and the server communicates with it through the platform's WebService API.

The main data area is opportunities, called “Potentials” in the tool documentation. Agents can list records with optional filters, retrieve a complete opportunity by ID, search by name, create records, and update existing records. Contact search supports names, email addresses, and companies. Opportunity-related tools can also add notes and list linked activities.

The server includes two discovery-oriented operations. describe_modulo reports the fields available in a VTENext module, while query_raw accepts a VTQL SELECT query for read-only access to data that may not be covered by the dedicated tools.

How it works

The Castaldo-Solutions/mcp-vtenext MCP server runs as a local Node.js process and exposes its functions through MCP. It requires Node.js 18 or newer and a reachable VTENext installation, either self-hosted or running in Docker.

Authentication follows the vtiger WebService sequence. The server requests a challenge from webservice.php, combines the returned token with the configured access key, hashes that value with MD5, and submits a form-encoded login request. The resulting session name is reused through a cached session. The README states that sessions are cached for four minutes, within the five-minute token lifetime.

Set READ_ONLY=true when the client should not change CRM data. In that mode, the create-opportunity, update-opportunity, and add-note tools return errors rather than writing to VTENext. Read operations remain available.

Setup and configuration

The documented local setup changes into the server directory, installs its npm dependencies, and copies .env.example to .env. Configure these values:

• VTENEXT_URL: URL of the VTENext instance.
• VTENEXT_USERNAME: VTENext user used for authentication.
• VTENEXT_ACCESS_KEY: access key for that user, found under Admin, Users, the selected user, and Access Key.
• READ_ONLY: optional setting that disables the supported write operations when set to true.

The project is also published on npm as @castaldosolutions/mcp-vtenext. The README shows a Node command using the server's local index.js in an MCP configuration and documents a .mcp.json example for Claude Code.

Tools and capabilities

The available operations are:

• List, retrieve, search, create, and update opportunities.
• Search contacts by name, email, or company.
• Add notes to opportunities.
• List activities associated with opportunities.
• Inspect fields for a VTENext module.
• Run raw, read-only VTQL queries.

The write operations are limited to opportunity creation, opportunity updates, and adding opportunity notes. query_raw is explicitly read-only, and the server-wide read-only setting blocks the three write tools above.

Limitations and notes

The Castaldo-Solutions/mcp-vtenext MCP server requires a running VTENext instance and valid WebService credentials; it does not provide the CRM itself. The supplied material documents opportunity and contact workflows, activity listing, notes, module inspection, and raw read queries, but does not establish support for other record types or arbitrary VTENext mutations.

Unit tests can run without VTENext. Integration tests require a live instance at VTENEXT_URL. The project is released under the MIT license.