# Castaldo-Solutions/mcp-vtenext [Health: Active]

**Category:** 📊 Data Platforms  
**Repository:** https://github.com/Castaldo-Solutions/mcp-vtenext  
**GitHub Stars:** 4  
**npm Downloads (last month):** 49  
**Views:** 3  
**Installs:** 0  
**Upvotes:** 0  
**Directory Page:** https://allmcps.com/mcp/castaldo-solutions-mcp-vtenext

## Description
MCP server for VTENext CRM (open-source vtiger-based). Query, create and update opportunities and contacts via the WebService API. Available on npm as @castaldosolutions/mcp-vtenext.

## Tools
Capabilities this server exposes over MCP:

- **list_opportunita** — Elenca le opportunità con filtri opzionali
- **get_opportunita** — Recupera i dettagli completi di un'opportunità tramite ID
- **search_opportunita** — Cerca opportunità per nome
- **create_opportunita** — Crea una nuova opportunità in VTENext
- **update_opportunita** — Aggiorna i dati di un'opportunità esistente
- **search_contatti** — Cerca contatti per nome, email o azienda
- **add_nota_opportunita** — Aggiunge una nota/commento a un'opportunità
- **list_attivita_opportunita** — Elenca le attività associate a un'opportunità
- **describe_modulo** — Mostra i campi disponibili per un modulo VTENext
- **query_raw** — Esegue una query VTQL grezza su VTENext (solo lettura)

## Claude Desktop Quick Installation
Heuristic fallback — verify the package name and runner against the repository README before running it. Uses `npx` (confidence: low):

```json
"mcpServers": {
  "mcp-vtenext": {
    "command": "npx",
    "args": ["-y","castaldo-solutions-mcp-vtenext"],
    "env": {
      "VTENEXT_URL": "",
      "VTENEXT_USERNAME": "",
      "VTENEXT_ACCESS_KEY": ""
    }
  }
}
```

**Requires environment variables:** `VTENEXT_URL`, `VTENEXT_USERNAME`, `VTENEXT_ACCESS_KEY` — the values above are empty placeholders; fill in real credentials before running (see the repository for what each one is for).

## Documentation

## 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.

_Full upstream README: https://allmcps.com/mcp/castaldo-solutions-mcp-vtenext/readme_