vtiger-mcp

MCP server + CLI for vtiger CRM. Connect any AI agent (Claude Desktop, Claude Code, Cursor, …) to your vtiger CRM to log timesheets and create / update records in any module — in plain English.

It talks to vtiger's built-in REST API (/webservice.php, available in vtiger 6.x / 7.x). It adds no access rules of its own: every call runs as the authenticated user, so vtiger enforces that user's role, profile, and row-level sharing automatically. Each person uses their own Webservice Access Key, so they only see and change what their account already allows.

New to the terminal? See SETUP.md for a click-by-click, non-developer guide.

---

🤖 Install with an AI agent (copy-paste prompt)

Don't want to edit config files yourself? Copy the whole prompt below and paste it into an AI agent that can edit files (Claude Code, Cursor, Windsurf, Gemini CLI, OpenAI Codex, VS Code Copilot Agent, …). It will ask for your details and set everything up for you.

Install and configure the "vtiger-mcp" MCP server for me (npm package name: vtiger-mcp).
It lets me log vtiger CRM timesheets and create/update records in any module from this agent.

Do this:
1. Verify Node.js 18+ is installed (run: node --version). If it's missing, tell me to install
   the LTS from https://nodejs.org and stop.
2. Ask me for these and WAIT for my answers:
   - VTIGER_URL: my vtiger base URL, e.g. https://yourcrmdomain.com (no /webservice.php)
   - VTIGER_USERNAME: my vtiger login username
   - VTIGER_ACCESS_KEY: my "Webservice Access Key" from vtiger -> My Preferences (NOT my password)
3. Detect which MCP client I use and find its config file:
   - Claude Desktop: %APPDATA%\Claude\claude_desktop_config.json (Windows) or
     ~/Library/Application Support/Claude/claude_desktop_config.json (macOS)
   - Cursor: ~/.cursor/mcp.json ; Windsurf: ~/.codeium/windsurf/mcp_config.json ;
     Gemini CLI: ~/.gemini/settings.json  (all use the "mcpServers" JSON key)
   - VS Code: ./.vscode/mcp.json  (uses a top-level "servers" key with "type": "stdio")
   - OpenAI Codex CLI: ~/.codex/config.toml  (TOML table [mcp_servers.vtiger])
   If you can't tell, ask me which client I'm using.
4. Back up that file, then MERGE IN (do not overwrite my other servers) a server named "vtiger":
   command: npx
   args: ["-y", "vtiger-mcp"]
   env: { VTIGER_URL, VTIGER_USERNAME, VTIGER_ACCESS_KEY, VTIGER_ALLOW_DELETE: "false" }
   Use the correct shape for my client (mcpServers JSON, VS Code "servers", or Codex TOML).
5. Keep my access key ONLY in this local config. Never commit it, echo it back in full, or share it.
6. (Optional) Verify auth by running, with those env vars set:  npx -p vtiger-mcp vtiger whoami
   It should print my vtiger userId.
7. Tell me to fully quit and reopen my client, then try: "list my vtiger modules"
   or "log 2 hours to <task name> today".

Prefer to do it manually? See CLIENTS.md for every client's exact config.

---

Features

• 🔐 Per-user auth via each user's Webservice Access Key — row-level access preserved, nothing centralized.
• 🧩 Any module: create, update, query, describe, retrieve, delete — subject to the user's permissions.
• ⏱️ Timesheet helpers for the time-tracking module (create/list/update entries, resolve tasks by name).
• 🖥️ Ships as both an MCP server (for AI agents) and a CLI.
• 📦 Zero changes to your vtiger install. Node 18+, no native deps.

Requirements

• Node.js 18+
• A vtiger CRM (6.x / 7.x) whose /webservice.php endpoint is reachable
• Your Webservice Access Key — in the CRM: My Preferences → "Webservice Access Key" (a 16-char string; not your login password)

Install

# Global (gives you the `vtiger` CLI and the `vtiger-mcp` server binary)
npm install -g vtiger-mcp

# …or run without installing
npx vtiger-mcp        # starts the MCP server (stdio)

Or from source:

git clone https://github.com/ViralP17/vtiger-mcp.git
cd vtiger-mcp
npm install
npm run build

Configure

Set three environment variables (via your MCP client config, or a .env file for the CLI — see .env.example):

Variable	Example	Notes
VTIGER_URL	https://yourcrmdomain.com	Base URL, no /webservice.php
VTIGER_USERNAME	your.username	Your vtiger login
VTIGER_ACCESS_KEY	xxxxxxxxxxxxxxxx	Webservice Access Key
VTIGER_ALLOW_DELETE	false	Set true to allow delete

Use as an MCP server

Point your AI client at vtiger-mcp and pass your credentials in env.

Via npx (after npm install -g vtiger-mcp or letting npx fetch it):

{
  "mcpServers": {
    "vtiger": {
      "command": "npx",
      "args": ["-y", "vtiger-mcp"],
      "env": {
        "VTIGER_URL": "https://yourcrmdomain.com",
        "VTIGER_USERNAME": "your.username",
        "VTIGER_ACCESS_KEY": "your-access-key",
        "VTIGER_ALLOW_DELETE": "false"
      }
    }
  }
}

From a source checkout (use node + the built server path):

{
  "mcpServers": {
    "vtiger": {
      "command": "node",
      "args": ["/path/to/vtiger-mcp/dist/mcp/server.js"],
      "env": { "VTIGER_URL": "https://yourcrmdomain.com", "VTIGER_USERNAME": "your.username", "VTIGER_ACCESS_KEY": "your-access-key" }
    }
  }
}

• Claude Desktop config: %APPDATA%\Claude\claude_desktop_config.json (Windows) / ~/Library/Application Support/Claude/claude_desktop_config.json (macOS)

📎 Using Cursor, VS Code, Windsurf, Antigravity, OpenAI Codex CLI, Gemini CLI, or another client? See CLIENTS.md for the exact config file and format for each — it's the same server everywhere.

Then just ask, e.g. "Log 3 hours to the Website Redesign task today as regular hours" or "Show my timesheets this week."

Use as a CLI

export VTIGER_URL=https://yourcrmdomain.com
export VTIGER_USERNAME=your.username
export VTIGER_ACCESS_KEY=your-access-key   # or put these in a .env file

vtiger whoami
vtiger modules
vtiger describe TimeControl
vtiger query "SELECT tc_code, date_start, totaltime FROM TimeControl LIMIT 5;"
vtiger log-timesheet --task "Website Redesign" --start 10:00 --end 13:00 --type "Regular Hours" --activity "API work"
vtiger my-timesheets --from 2026-07-01 --to 2026-07-31
vtiger create ProjectTask --set projecttaskname="Write docs" --set projectid=<id>
vtiger update 17x1234 --set description="Revised notes"

Tools exposed to the AI agent

Any module (scoped to your access):

Tool	What it does
list_modules	Modules you can access
describe_module	Live fields of a module (names, mandatory, picklists, references)
query	Read-only VTQL SELECT
retrieve_record	Fetch one record by id
create_record	Create a record in any writable module
update_record	Partial update of a record
delete_record	Delete (only if VTIGER_ALLOW_DELETE=true)

Timesheet helpers (the time-tracking module):

Tool	What it does
whoami	Your vtiger user id / profile
list_my_projects	Projects you can access
list_my_tasks	Project tasks (for the related_to link)
log_timesheet	Add a daily entry (resolves task, defaults date/owner, computes total)
list_my_timesheets	Your entries in a date range
update_timesheet	Edit an existing entry

Notes & tips

• Field names vary per install. vtiger schemas are customizable, so always describe_module (or vtiger describe <Module>) first to learn the exact field names before creating/updating.
• Ids are vtiger "webservice ids" like 17x1234 (<moduleId>x<recordId>). Reference fields (owner, related_to, projectid) expect these ids; the timesheet helpers resolve task names to ids for you.
• The timesheet module is configurable (see below). It defaults to TimeControl; point it at your module without touching code.
• Deletes are off by default. Set VTIGER_ALLOW_DELETE=true only if you want the agent/CLI to delete records (and your account has that right).
• Security. Your access key is a secret — keep it in your local .env or client config only. Use HTTPS. Nothing is centralized; each user runs their own copy with their own key.

Configuring the timesheet module (other vtiger installs)

The timesheet helpers default to the TimeControl module with ProjectTask/Project links. If your install uses different module or field names, set these env vars (all optional) — no code changes needed:

Variable	Default	Purpose
VTIGER_TIMESHEET_MODULE	TimeControl	Time-entry module
VTIGER_TASK_MODULE	ProjectTask	Module linked from an entry
VTIGER_PROJECT_MODULE	Project	Project module

Advanced field-name overrides (rarely needed): VTIGER_TS_DATE_START_FIELD, VTIGER_TS_DATE_END_FIELD, VTIGER_TS_TIME_START_FIELD, VTIGER_TS_TIME_END_FIELD, VTIGER_TS_RELATED_FIELD, VTIGER_TS_DESC_FIELD, VTIGER_TS_HOURSTYPE_FIELD, VTIGER_TS_TOTAL_FIELD, VTIGER_TS_OWNER_FIELD, VTIGER_TASK_NAME_FIELD, VTIGER_TASK_PROJECT_FIELD, VTIGER_PROJECT_NAME_FIELD. See .env.example for the full list and defaults.

Whatever your modules are named, the generic create_record, update_record, query, and describe_module tools always work.

License

MIT © ViralP17