Vtiger CRM MCP Server

A Model Context Protocol (MCP) server that provides tools for interacting with Vtiger CRM through its REST API. Supports both stdio and HTTP/WebSocket transports for local and remote usage.

Features

Dual Transport Support: stdio for local usage, HTTP/WebSocket for remote access
Complete Vtiger CRM API integration
TypeScript support with full type safety
Comprehensive CRUD operations
Advanced querying and search capabilities
Proper authentication handling
Error handling and validation
Health check and info endpoints
CORS support for web clients

Installation

Clone the repository
Install dependencies:
npm install
Configure environment variables:
cp .env.example .env # Edit .env with your Vtiger credentials and server settings
Build the project:
npm run build

Usage

Option 1: Stdio Transport (Local/Process-based)

npm run start:stdio
# or
node dist/index.js --transport=stdio

Option 2: HTTP Transport (Remote/Network-based)

npm run start:http
# or
node dist/index.js --transport=http --port=3001 --host=0.0.0.0

Development Mode

npm run dev          # Default stdio
npm run dev:http     # HTTP on port 3001

Configuration

Environment Variables

# Vtiger CRM Configuration
VTIGER_BASE_URL=https://your-vtiger-instance.com
VTIGER_USERNAME=your-username
VTIGER_ACCESS_KEY=your-access-key

# MCP Server Configuration
MCP_TRANSPORT=http        # 'stdio' or 'http'
MCP_PORT=3001            # Port for HTTP transport
MCP_HOST=0.0.0.0         # Host for HTTP transport

Command Line Arguments

node dist/index.js --transport=http --port=3001 --host=localhost

Remote Access Endpoints

When running with HTTP transport:

WebSocket MCP Endpoint: ws://your-server:3001/mcp
Health Check: http://your-server:3001/health
Server Info: http://your-server:3001/info

MCP Client Configuration

For Local MCP Clients (stdio)

{
  "mcpServers": {
    "vtiger-crm": {
      "command": "node",
      "args": ["/path/to/vtiger-mcp-server/dist/index.js", "--transport=stdio"]
    }
  }
}

For Remote MCP Clients (WebSocket)

{
  "mcpServers": {
    "vtiger-crm": {
      "url": "ws://your-server.com:3001/mcp"
    }
  }
}

Available Tools

vtiger_list_modules: List all available modules
vtiger_describe_module: Get module metadata and fields
vtiger_create_record: Create new records
vtiger_retrieve_record: Get specific records by ID
vtiger_update_record: Update existing records
vtiger_delete_record: Delete records
vtiger_query: Execute custom queries
vtiger_search: Search across modules
vtiger_sync: Get modified records

API Examples

Using the MCP Client (Programmatic)

import { createVtigerClient } from './src/client/mcp-client.js';

// Connect to remote MCP server
const client = await createVtigerClient('ws://localhost:3001/mcp');

// List available tools
const tools = await client.listTools();

// Create a lead
const result = await client.callTool('vtiger_create_record', {
  module: 'Leads',
  data: {
    firstname: 'John',
    lastname: 'Doe',
    email: 'john.doe@example.com',
    company: 'Example Corp'
  }
});

// Search for contacts
const contacts = await client.callTool('vtiger_search', {
  searchValue: 'john',
  module: 'Contacts'
});

await client.disconnect();

Health Check

curl http://localhost:3001/health

Response:

{
  "status": "ok",
  "timestamp": "2025-01-01T12:00:00.000Z"
}

Server Info

curl http://localhost:3001/info

Response:

{
  "name": "vtiger-mcp-server",
  "version": "1.0.0",
  "capabilities": {
    "tools": {}
  }
}

Deployment

Docker Deployment

Create a Dockerfile:

FROM node:18-alpine

WORKDIR /app
COPY package*.json ./
RUN npm ci --only=production
COPY dist ./dist
COPY .env .env

EXPOSE 3001
CMD ["node", "dist/index.js", "--transport=http", "--port=3001", "--host=0.0.0.0"]

PM2 Deployment

{
  "name": "vtiger-mcp-server",
  "script": "dist/index.js",
  "args": ["--transport=http", "--port=3001"],
  "env": {
    "NODE_ENV": "production",
    "MCP_TRANSPORT": "http",
    "MCP_PORT": "3001"
  }
}

Nginx Reverse Proxy

upstream vtiger_mcp {
    server localhost:3001;
}

server {
    listen 80;
    server_name your-domain.com;

    location /mcp {
        proxy_pass http://vtiger_mcp;
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection "upgrade";
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
    }

    location /health {
        proxy_pass http://vtiger_mcp;
    }

    location /info {
        proxy_pass http://vtiger_mcp;
    }
}

Security Considerations

Network Security: When exposing via HTTP, ensure proper firewall rules
HTTPS: Use HTTPS/WSS in production with proper SSL certificates
Authentication: Consider adding authentication middleware for HTTP transport
CORS: Configure CORS appropriately for your use case
Rate Limiting: Implement rate limiting for production deployments

Monitoring

The server provides several monitoring endpoints:

/health - Basic health check
/info - Server information and capabilities
Console logs for connection events and errors

Development

npm run dev          # Development with hot reload (stdio)
npm run dev:http     # Development with hot reload (HTTP)
npm run type-check   # Type checking only
npm run build        # Production build

Troubleshooting

Common Issues

Connection Refused: Check if the server is running and port is accessible
Authentication Errors: Verify Vtiger credentials in .env
WebSocket Connection Failed: Ensure firewall allows WebSocket connections
CORS Issues: Check CORS configuration for web clients

Debug Mode

Set DEBUG=1 environment variable for detailed logging:

DEBUG=1 npm run start:http

This server cannot be installed

security - not tested

license - not found

quality - not tested

A Model Context Protocol server that provides tools for interacting with Vtiger CRM through its REST API.

Related MCP Servers

salesforce-mcp-server
kablewy
A
security
F
license
A
quality
A Model Context Protocol server implementation for interacting with Salesforce through its REST API.
Last updated -
4
10
TypeScript
ConnectWise API Gateway MCP Server
jasondsmith72
-
security
F
license
-
quality
A Model Context Protocol server that provides a comprehensive interface for interacting with the ConnectWise Manage API, simplifying API discovery, execution, and management for both developers and AI assistants.
Last updated -
46
2
Python
Harvest Time Tracking MCP Server
CodifyAG
-
security
A
license
-
quality
A Model Context Protocol server implementation that wraps Harvest's REST API, enabling seamless interaction with Harvest's time tracking, client, project, and reporting features through MCP clients.
Last updated -
3
Python
MIT License
Ollama_MCP_Guidance
ShadovvSinger
-
security
A
license
-
quality
A Model Context Protocol server that provides standardized interfaces for interacting with Ollama API, offering JSON responses, error handling, and intelligent guidance for LLM-based API calls.
Last updated -
Python
MIT License

View all related MCP servers

Vtiger CRM MCP Server