# Kylas CRM [Health: Active]

**Category:** 👤 Customer Data Platforms  
**Repository:** https://github.com/kylastech/kylas-crm-mcp-server  
**GitHub Stars:** 12  
**Views:** 1  
**Installs:** 0  
**Upvotes:** 0  
**Directory Page:** https://allmcps.com/mcp/kylas-crm-2

## Description
MCP server for Kylas CRM: create, search, and manage leads. Requires KYLAS_API_KEY.

## Tools
Capabilities this server exposes over MCP:

- **get_lead_field_instructions** — Get all lead fields for the current tenant. CALL THIS FIRST before creating a lead.
Returns a cheat sheet with API names (standard fields), Field IDs (custom fields), and Picklist Option IDs.
Use this to build field_values for create_lead based on what the user wants—do not use static fields.
- **get_current_user** — Get the current authenticated user's profile from Kylas (GET /users/me).
Call this whenever a date or datetime-related query is involved.
Returns timezone (IANA, e.g. Asia/Calcutta), recordActions (call, email, sms, etc.), name, and other profile fields.
- For filtering (search_leads, search_idle_leads): use the returned timezone as the timeZone in date/datetime filters; keep the user's date/datetime as-is (do not convert to UTC).
- For create_lead: when the user provides a datetime in their own words (e.g. "11th Feb 2026 at 7:30 AM"), interpret it in this timezone, convert to UTC using parse_datetime_to_utc_iso, and send the UTC ISO string in field_values.
- **lookup_users** — Look up users by name, or list all users in the system.
- Use return_all=True (with query "name:" or empty) to fetch all users in one response (all pages combined).
- For name search: query in field:value form (e.g. "firstName:last", "name:Last"). If one user is found, use that ID in search_leads; if multiple, ask which one.
query: Search string (e.g. "firstName:last", "name:Last"). Use "name:" or leave default to list all when return_all=True.
page: 0-based page (default 0). Ignored when return_all=True.
size: Page size, max 50 (default 50). Used per page when return_all=True.
return_all: If True, fetch all pages and return every user in one response (cap 500).
- **lookup_products** — Look up products by name. Use this BEFORE filtering leads by product when the user gives a product name.
- If one product is found, use that product's ID in search_leads (e.g. {"field": "products", "operator": "equal", "value": <id>}).
- If multiple products are found, ask the user which product they mean (list the options), then use the chosen product's ID in search_leads.
query: Search string. Use "name:<product_name>" (e.g. "name:Widget") or just the product name (e.g. "Widget"); the server will send name:value to the API.
page: 0-based page (default 0).
size: Max 50 (default 50).
- **lookup_pipelines** — Look up pipelines by name (for leads). Use when the user asks for leads by stage (e.g. open/closed/won/lost) but does not specify which pipeline.
- Call this first; do NOT call get_pipeline_stages until after the user confirms the pipeline.
- Present the pipeline(s) (id and name) and ask the user which pipeline they mean. If only one pipeline is found, still ask for confirmation.
- Only after the user confirms, call get_pipeline_stages with that pipeline ID to get stages for that pipeline, then search_leads.
query: Search string. Use "name:<pipeline_name>" or just the pipeline name; empty string returns all pipelines for the entity.
entity_type: Entity type (default LEAD).
page: 0-based page (default 0).
size: Max 50 (default 50).
- **get_pipeline_stages** — Get stages for a pipeline. Call this only after the user has confirmed which pipeline to use (from lookup_pipelines). Do not call before pipeline confirmation.
Returns pipeline name and list of stages for that pipeline only, with id, name, and forecastingType (OPEN, CLOSED_WON, CLOSED_LOST, CLOSED_UNQUALIFIED).
Use the stage IDs in search_leads: filters [{"field": "pipeline", "operator": "equal", "value": pipeline_id}, {"field": "pipelineStage", "operator": "equal", "value": stage_id}].
If the user said "open leads" or "closed leads" and more than one stage has the same forecastingType, ask which stage they mean.
pipeline_id: The pipeline ID (from lookup_pipelines).
- **get_pipeline_details** — Get full pipeline details by ID (GET /pipelines/{id}): stages plus unqualifiedReasons and lostReasons.
Call this when moving a lead to Closed Lost or Closed Unqualified. Present the relevant reasons list to the user,
ask them to pick one, then call update_lead with pipelineStageReason set to that exact string (e.g. "No followup", "Booked with competitor").
pipeline_id: The pipeline ID (from the lead's current pipeline or from lookup_pipelines).
- **parse_datetime_to_utc_iso_tool** — Parse a datetime string in the user's timezone and return UTC ISO string for the Kylas API.
Call get_current_user first to get the user's timezone. Use the returned string in create_lead field_values for date/datetime fields.
Example: user says "create lead with follow-up 11th Feb 2026 at 7:30 AM" → get_current_user → timezone Asia/Calcutta → parse_datetime_to_utc_iso_tool("11 Feb 2026 7:30 AM", "Asia/Calcutta") → use result in field_values.
local_datetime: Datetime as the user said it (e.g. "11 Feb 2026 7:30 AM", "11th Feb 2026 at 7:30 am").
timezone: IANA timezone from get_current_user (e.g. Asia/Calcutta).
- **create_lead** — Create a lead in Kylas CRM with only the fields the user wants (no static field list).

You MUST call get_lead_field_instructions FIRST to get valid API names and Field IDs.
Infer from user context which fields to send; include only those in field_values.

field_values: Map of field identifier to value.
- Standard fields: use API name as key at top level (e.g. firstName, lastName, companyName, emails, phoneNumbers, leadSource, isNew).
- Custom fields: MUST be under "customFieldValues" with **internal name** as key (e.g. "customFieldValues": {"cfLeadCheck": "Checked"}). Do not use field ID as key—Kylas expects internal names. If you pass a field ID (e.g. "1210985"), the server will resolve it to the internal name (e.g. cfLeadCheck) automatically.
- For a single email use "email": "user@example.com". For phones use "phone": "5551234567" (or "phoneNumbers" array) and you MUST include "phone_country_code": "IN" or "+91" at top level. If the user provided phone(s) but did not specify country or dial code, do NOT call create_lead—ask the user (e.g. which country/dial code for these numbers?) and only call after they respond. Do not infer from currency or other context. Email types: OFFICE, PERSONAL. Phone types: MOBILE, WORK, HOME, PERSONAL. Exactly one email and at most one phone should be primary; first entry is primary by default.
- For picklists use the Option ID (number) from the cheat sheet.
- For date/datetime fields: the user gives a time in their timezone (e.g. "11th Feb 2026 at 7:30 AM"). Call get_current_user, then parse_datetime_to_utc_iso_tool(local_datetime, timezone) and put the returned UTC ISO string in field_values.
- **update_lead** — Update a lead in Kylas CRM. Fetches the lead first, merges your field_values into it, then PUTs the full body.
Same field_values format as create_lead. Call get_lead_field_instructions first for API names and custom field internal names.
For owner: use lookup_users to get the user ID, then pass ownerId: <id> in field_values.

lead_id: The lead ID to update (e.g. from search_leads or search_leads_by_term results).
field_values: Map of field identifier to value (same as create_lead: firstName, lastName, email, phone with phone_country_code, customFieldValues, picklist Option IDs, date/datetime in UTC ISO, etc.). These are merged over the existing lead; other fields are left unchanged.
- **get_lead** — Get full details of a lead by ID (GET /leads/{id}). Use when the user asks for complete lead info, lead details, or to view a specific lead.
lead_id: The lead ID (e.g. from search_leads or search_leads_by_term results).
- **search_leads** — Search/filter leads. Only fields marked [FILTERABLE] in get_lead_field_instructions can be used.
Call get_lead_field_instructions first to get filterable fields and their types.
- **search_leads_by_term** — Search leads by a single term across multiple fields (firstName, lastName, companyName, phoneNumbers, emails, etc.).
Use this when the user asks for "leads with X", "leads containing Y", or "leads named Z" without specifying which field to filter on.
For filtering by a specific field (e.g. "leads where phone number is X"), use search_leads instead.

search_term: The term to search for (e.g. "akshay", "acme").
page: 0-based page (default 0).
size: Page size, max 100 (default 20).
sort: Sort e.g. "updatedAt,desc" (default).
- **search_idle_leads** — Search for idle/stagnant leads: no activity for at least the given number of days.
Uses both updatedAt and latestActivityCreatedAt; a lead is returned only when BOTH dates
are on or before (today − days), so the effective last activity is before the threshold.

days: Minimum days with no activity (e.g. 10 for "no activity since 10 days").
time_zone: IANA timezone for threshold (e.g. America/New_York). Default: Asia/Calcutta.
page: 0-based page (default 0).
size: Page size, max 100 (default 20).
sort: Sort e.g. "createdAt,desc" (default).

## Claude Desktop Quick Installation
Install path detected from listing signals. Uses `uvx` (confidence: high):

```json
"mcpServers": {
  "kylas-crm": {
    "command": "uvx",
    "args": ["kylas-crm-mcp-server"],
    "env": {
      "KYLAS_API_KEY": "",
      "KYLAS_BASE_URL": ""
    }
  }
}
```

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

## Documentation

## What Kylas CRM MCP server does

The Kylas CRM MCP server exposes lead-focused operations from Kylas CRM through the Model Context Protocol. It supports creating leads, searching and filtering existing leads, and identifying leads that have had no activity for a specified number of days. The scope is limited to lead operations rather than a general-purpose interface for every Kylas CRM object.

It also provides lookup functions that help an agent work with Kylas identifiers. User names can be resolved to IDs for fields such as owner or creator, product names can be converted to product IDs, and pipeline and stage information can be retrieved for open, closed, or won leads. A schema instruction tool returns standard and custom lead fields along with picklist IDs, which can guide dynamically constructed lead requests.

## How it works

The Kylas CRM MCP server uses stdio transport. An MCP client starts the Python module and exchanges messages with it through standard input and output. The server then uses the configured Kylas API connection to perform the requested lead operation.

The repository supports running `python -m kylas_crm_mcp`, or `python main.py` during development from the repository root. Its documented client examples are Cursor and Claude Desktop, although the transport is the standard MCP stdio pattern.

## Setup and configuration

Python 3.10 or newer is required, along with a Kylas account and API key.

Set `KYLAS_API_KEY` before starting the server. `KYLAS_BASE_URL` is optional and defaults to `https://api.kylas.io/v1`. Configuration can be supplied through environment variables or a `.env` file. For container use, build the provided Docker image and pass the API key when starting the container with interactive input enabled.

## Tools and capabilities

The available operations cover:

- Retrieving standard and custom lead-field instructions and picklist IDs.
- Creating leads with fields supplied from the agent’s context.
- Searching and filtering leads by multiple criteria.
- Finding leads with no activity for a chosen number of days.
- Resolving users and products by name to their Kylas IDs.
- Resolving pipelines and retrieving their stages.

These lookup operations are useful when a create or search request needs identifiers that are not already known to the agent.

## Limitations and notes

The implementation is described as lead-only, so the documented capabilities should be evaluated against workflows that center on Kylas leads. A valid Kylas API key is required for normal use. The optional base URL can change the API endpoint, but the documented default points to Kylas’s version-one API path.

Development instructions include installing the development dependencies and running `pytest`.

_Full upstream README: https://allmcps.com/mcp/kylas-crm-2/readme_