Uniware Vtiger Server

Read-only MCP server that connects Claude to Vtiger CRM for Uniware's Account Manager (AM) Copilot. Phase 1 exposes briefing tools for leads, deals, and overdue follow-ups.

Repository: https://github.com/Srimathi-8502/Mcp_Vtiger_claude

MCP tools

Tool	Description
get_leads_by_owner	Leads assigned to an AM (organisation, status, follow-up fields)
get_deals_by_owner	Open deals for an AM (organisation, stage, amount, last contacted, follow-up)
get_overdue_followups	Leads and deals with follow-up date on or before today

All tools take an owner argument — the Vtiger user ID (e.g. 19x5) agreed with your CRM admin.

Requirements

• Python 3.12+
• Network access to your Vtiger instance (VTIGER_BASE_URL)
• Vtiger API username and access key

Quick start

# Clone
git clone https://github.com/Srimathi-8502/Mcp_Vtiger_claude.git
cd Mcp_Vtiger_claude

# Virtual environment
python -m venv .venv
# Windows
.venv\Scripts\activate
# Linux / macOS
source .venv/bin/activate

pip install -r requirements.txt

# Configure
cp .env.example .env
# Edit .env with Vtiger credentials and MCP_API_KEY

# Run
set PYTHONPATH=src          # Windows CMD
# export PYTHONPATH=src     # Linux / macOS
vtiger-mcp
# or: uvicorn vtiger_mcp.main:app --host 0.0.0.0 --port 8000

Server defaults to http://0.0.0.0:8000. MCP HTTP endpoint is served by FastMCP on the same app.

Environment variables

Copy .env.example to .env. Key settings:

Variable	Required	Description
MCP_API_KEY	Yes	Secret Claude sends as X-API-Key when calling this server
MCP_AUTH_TOKEN	No	Optional Bearer token (FastMCP native auth)
VTIGER_BASE_URL	Yes	e.g. https://usp.od2.vtiger.com
VTIGER_USERNAME	Yes	Vtiger API user
VTIGER_ACCESS_KEY	Yes	Vtiger webservice access key
VTIGER_OPEN_DEAL_STAGES	No	Comma-separated stages; empty = all deals for owner
VTIGER_FIELD_*	Partial	CRM field API names; at least one follow-up date field required for /ready

Generate an API key:

python -c "import secrets; print(secrets.token_urlsafe(32))"

See .env.example for the full list of field-mapping variables.

Confirmed Deals field mapping (Potentials module)

Deals use the Vtiger module Potentials (not Deals).

Briefing field	Vtiger API name	Env var
Assigned AM	assigned_user_id	VTIGER_FIELD_DEAL_OWNER
Deal name	potentialname	VTIGER_FIELD_DEAL_NAME
Organization	related_to	VTIGER_FIELD_DEAL_ORG (resolved to accountname via Accounts)
Deal stage	sales_stage	VTIGER_FIELD_DEAL_STAGE
Amount	amount	VTIGER_FIELD_DEAL_AMOUNT
Last contacted	last_contacted_on	VTIGER_FIELD_DEAL_LAST_CONTACTED
Next follow-up date	cf_potentials_nextfollowupdate	VTIGER_FIELD_DEAL_FOLLOWUP_DATE
Next follow-up description	nextstep	VTIGER_FIELD_DEAL_FOLLOWUP_DESC

Deal tool responses remap these to: owner, deal_name, organisation_id, organisation_name (resolved from Accounts), stage, amount, last_contacted_date, next_followup_date, next_followup_description.

Leads follow-up: Vtiger Leads has no next-follow-up date field (unlike Potentials cf_potentials_nextfollowupdate). get_overdue_followups returns deals only until a Leads date field exists in CRM. Use get_leads_by_owner for leads in the briefing.

Health checks

Endpoint	Purpose
GET /health	Liveness — always returns 200 if the process is up
GET /ready	Readiness — 200 when required config is present, 503 if degraded

These paths do not require authentication.

Authentication

Requests to MCP endpoints must include one of:

• X-API-Key: <MCP_API_KEY>
• Authorization: Bearer <MCP_API_KEY> (or MCP_AUTH_TOKEN if set for FastMCP auth)

When registering the custom connector in Claude, use the deployed base URL and MCP_API_KEY.

Helper scripts

Run from the repo root with PYTHONPATH=src and .env loaded:

python scripts/connection_check.py   # Vtiger login + MCP health probe
python scripts/mcp_check.py            # MCP tool smoke test
python scripts/describe_fields.py    # Inspect Vtiger module fields
python scripts/describe_raw.py       # Full describe JSON for Leads/Potentials
python scripts/test_tools.py         # Exercise CRM tools

Docker

docker build -t uniware-vtiger-mcp .
docker run --env-file .env -p 8000:8000 uniware-vtiger-mcp

Deploy (Render)

render.yaml defines a web service:

• Build: pip install -r requirements.txt
• Start: PYTHONPATH=src uvicorn vtiger_mcp.main:app --host 0.0.0.0 --port $PORT
• Health: /health

Set environment variables in the Render dashboard (or GitLab CI) — do not commit .env.

Project layout

src/vtiger_mcp/
  main.py           # FastMCP app, health routes, uvicorn entry
  config.py         # Settings from environment
  middleware.py     # API key validation
  tools/crm.py      # MCP tool definitions
  vtiger/client.py  # Vtiger webservice client
scripts/            # Local verification scripts
docs/               # Technical architecture and project history

See docs/TECHNICAL.md for architecture and request flow.
See docs/PROJECT_JOURNEY_AND_TECHNICAL_HISTORY.md for full project journey, issues, and module reference.

Security

• Never commit .env or Vtiger access keys.
• Phase 1 is read-only — no create/update/delete operations.
• Rotate MCP_API_KEY if it is exposed.

License

Internal Uniware project.