Freshsales MCP Server
This is a local stdio MCP server for Freshsales that exposes 31 tools to read and write CRM data across leads, contacts, accounts, deals, tasks, appointments, and notes.
Discover saved views, field definitions/dropdown choices (including custom
cf_*fields), owners, and run unified CRM search.Manage contacts: list by view, view details, create, update, and search.
Manage accounts/companies: list by view, view details, list linked contacts, create, update, and search.
Manage deals: list by view, view details, create, update (e.g. stage/amount/owner), and search.
Manage leads: list by view, view details, create, update, and search (permission-gated by Freshsales role).
Manage tasks: list by filter (open/due today/overdue/all), create, and update/reschedule/reassign/mark done.
Manage appointments: list upcoming/past/all and create linked meetings.
Add notes to contacts, accounts, deals, or leads.
It runs locally via node dist/index.js and uses FRESHSALES_DOMAIN plus FRESHSALES_API_KEY from the client environment.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@Freshsales MCP Server look up the Acme Corp deal and add a note that we sent the proposal"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
Freshsales MCP Server
An MCP (Model Context Protocol) server for the Freshsales (Freshworks CRM) API. Provides 31 tools for managing leads, contacts, accounts, deals, tasks, appointments and notes from any MCP client (Claude Desktop, Claude Code, VS Code, ...).
Freshworks does not ship an official Freshsales MCP server, so this one wraps the REST API directly. It is the CRM companion to freshdesk_mcp and follows the same structure.
Disclaimer: Provided as-is, without warranty. You are solely responsible for how you use it and for any actions performed through the Freshsales API. Several tools create or modify real CRM records. Review tool actions before approving them in production.
How it runs
This is a local stdio server: your MCP client launches node dist/index.js as a child process and talks to it over stdin/stdout. There is nothing to host, no port to open, and no inbound network access. "Deploying" means building it once and registering it with your client. Your API key stays in that process's environment and is never sent to the model, only the results of tool calls are.
Related MCP server: GHL Coaching MCP Server
Prerequisites
Node.js 18 or newer (20+ recommended)
A Freshsales account and a personal API key
An MCP client
Setup
1. Get your API key and bundle alias
Log in to Freshsales, click your profile picture, then Settings > API Settings.
Copy your personal API key.
Work out your bundle alias: the host and path in your CRM's browser URL, up to and including
/crm/sales, withouthttps://. For most accounts this looks likeyourcompany.myfreshworks.com/crm/sales.
2. Clone and build
git clone https://github.com/jonnyanarx/freshsales_mcp.git
cd freshsales_mcp
npm install
npm run buildThis compiles src/ to dist/index.js, which is the file your MCP client runs.
3. Register it with your MCP client
Use the absolute path to dist/index.js in every example below.
Claude Code
claude mcp add --env FRESHSALES_DOMAIN=yourcompany.myfreshworks.com/crm/sales --env FRESHSALES_API_KEY=your_api_key freshsales -- node /absolute/path/to/freshsales_mcp/dist/index.jsOr commit-free, project-scoped: copy .mcp.json.example to .mcp.json in your project and fill in the values. .mcp.json is git-ignored in this repo so credentials are not committed by accident.
Claude Desktop
Edit claude_desktop_config.json (Windows: %APPDATA%\Claude\, macOS: ~/Library/Application Support/Claude/), then fully restart the app:
{
"mcpServers": {
"freshsales": {
"command": "node",
"args": ["/absolute/path/to/freshsales_mcp/dist/index.js"],
"env": {
"FRESHSALES_DOMAIN": "yourcompany.myfreshworks.com/crm/sales",
"FRESHSALES_API_KEY": "your_api_key"
}
}
}
}On Windows, escape backslashes in JSON paths (C:\\Users\\you\\freshsales_mcp\\dist\\index.js).
VS Code
Add the same block to .vscode/mcp.json, but VS Code names the top-level key servers instead of mcpServers.
4. Verify
Ask your client something read-only, such as "List my Freshsales owners" or "What views exist for deals?". Or smoke-test the server directly (it should print the tool count and exit):
printf '%s\n' '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2024-11-05","capabilities":{},"clientInfo":{"name":"probe","version":"0"}}}' '{"jsonrpc":"2.0","method":"notifications/initialized"}' '{"jsonrpc":"2.0","id":2,"method":"tools/list"}' | FRESHSALES_DOMAIN=yourcompany.myfreshworks.com/crm/sales FRESHSALES_API_KEY=your_api_key node dist/index.js5. Updating
git pull
npm install
npm run buildThen restart your MCP client so it relaunches the server.
Configuration
Variable | Required | Example |
| yes |
|
| yes | your personal API key |
The server exits immediately with an error if either is missing.
Available Tools (31 Total)
Discovery (4 tools)
Tool | Description |
| List saved views for a module; gives you the |
| Look up a field's valid dropdown values and whether it is required, including custom |
| List CRM users and their |
| Unified search across leads, contacts, accounts and deals |
Contacts (5 tools)
Tool | Description |
| List contacts from a view |
| View contact details |
| Create a contact |
| Update a contact |
| Search contacts |
Accounts (6 tools)
Tool | Description |
| List accounts (companies) from a view |
| View account details |
| List every contact linked to an account (search is capped at 10 results) |
| Create an account |
| Update an account |
| Search accounts |
Deals (5 tools)
Tool | Description |
| List deals from a view |
| View deal details |
| Create a deal |
| Update a deal, e.g. move stage, change amount or owner |
| Search deals |
Leads (5 tools)
Tool | Description |
| List leads from a view |
| View lead details |
| Create a lead |
| Update a lead |
| Search leads |
Tasks (3 tools)
Tool | Description |
| List tasks (open, due today, overdue, all) |
| Create a task, optionally linked to a record |
| Reschedule, reassign or update a task |
Appointments (2 tools)
Tool | Description |
| List appointments (upcoming, past, all) |
| Create an appointment, optionally linked to a record |
Notes (1 tool)
Tool | Description |
| Add a note to a contact, account, deal or lead |
"Account" and "Company" are the same thing in Freshsales: the API module is sales_accounts, and a contact's link to its account is labelled "Company".
Things that differ from other CRM APIs
These were found by probing a live account rather than assumed:
Auth is
Authorization: Token token=<key>, not Basic or Bearer.Listing needs a view id. There is no flat "list all contacts". Call
list_viewsfor the module, then pass one of the ids tolist_contacts,list_accounts,list_dealsorlist_leads.Compound fields are objects. Emails and phone numbers are arrays of
{ value, is_primary, label }. The tools hide this: pass a plainemailstring and the client builds the array.Custom fields (
cf_*) are nested undercustom_fieldin the request body, never at the top level. Each instance has its own set, so tools accept a genericcustom_field: {...}object instead of hardcoding names.Custom picklists take the label, built-in dropdowns take the id. For a
cf_*picklist send the label string (e.g."EMEA"); for built-ins likedeal_stage_idsend the numeric id. Sending a numeric id to acf_*picklist is silently ignored: the API returns success but nothing changes andupdated_atdoes not move. Verify writes by re-reading the record.Required custom fields vary per instance and can make
create_dealfail.list_field_choicesreports whether a field is required.Leads access is permission-gated. Some roles can read the Leads field schema but get
403 Access Deniedon lead records. The lead tools return that error as a normal tool error.update_taskstatus: the exact accepted value for completing a task (e.g."COMPLETED") has not been verified; check the result and adjust if it is rejected.Rate limit: Freshsales allows about 1000 API requests per hour per account (HTTP 429 beyond that).
Usage examples
# Find views, then list deals in one
list_views with module "deals"
list_deals with view_id 12345, per_page 10
# Find a company, then its contacts' details
search_accounts with query "acme"
view_account with account_id 12345
# Look up valid values before writing
list_field_choices with module "deals", field "deal_stage_id"
update_deal with deal_id 12345, deal_stage_id 67890
# Create a contact linked to an account
create_contact with first_name "Ada", last_name "Lovelace", email "ada@example.com", company_id 12345
# Leave a note and schedule a follow-up
create_note with targetable_type "Deal", targetable_id 12345, description "Sent pricing"
create_task with title "Follow up", due_date "2026-12-01", targetable_type "Deal", targetable_id 12345Troubleshooting
Symptom | Likely cause |
Server exits immediately: environment variables are required |
|
| Wrong API key, or the key belongs to a user without access to that module |
| Your role lacks Leads permission (see above) |
|
|
| Hourly rate limit reached; wait and retry |
Tools do not appear in the client | Path to |
A write returns success but nothing changed | Likely a numeric id sent to a |
Server logs go to stderr (stdout is reserved for the MCP protocol), so check your client's MCP log for them.
Security
Treat the API key like a password. It carries all of your user's permissions in Freshsales.
Never commit
.mcp.jsonor.env(both are git-ignored). Use.mcp.json.exampleas the template.If a key is ever exposed, rotate it in Settings > API Settings.
Consider using a dedicated, least-privilege CRM user for the key.
Development
npm install
npm run build
npm start # needs FRESHSALES_DOMAIN and FRESHSALES_API_KEY setsrc/freshsales-client.ts: plain TypeScript API client (auth, HTTP, request/response shapes). No MCP code.src/index.ts: the MCP layer. Zod schemas, tool registration, text formatting.
License
MIT. See LICENSE.
Available Tools
30 toolscreate_accountC
Create a new account (company).
Inputs: name (required), city, tags, phone, +11 more.
create_appointmentC
Create an appointment/meeting, optionally linked to a contact/account/deal/lead.
Inputs: title (required), end_date (required), from_date (required), time_zone, +3 more.
create_contactC
Create a new contact.
Inputs: first_name (required), city, tags, email, +11 more.
create_dealA
Create a new deal. NOTE: many Freshsales instances mark extra custom (cf_*) fields as required on deal creation, and the create is rejected without them. list_field_choices(module="deals", field=...) reports whether a field is required; pass any required custom fields via custom_field.
Inputs: name (required), amount (required), tags, owner_id, +8 more.
create_leadD
Create a new lead.
Inputs: city, tags, email, state, +11 more.
create_noteC
Add a note to a contact, account, deal, or lead.
Inputs: description (required), targetable_id (required), targetable_type (required).
create_taskC
Create a task, optionally linked to a contact/account/deal/lead.
Inputs: title (required), due_date (required), owner_id, description, +3 more.
list_accountsA
List accounts (companies) from a saved view. Call list_views(module="sales_accounts") first to get a view_id.
Inputs: view_id (required), page, sort, per_page, +1 more.
list_appointmentsC
List appointments/meetings.
Inputs: page, filter, per_page.
list_contactsB
List contacts from a saved view. Call list_views(module="contacts") first to get a view_id.
Inputs: view_id (required), page, sort, per_page, +1 more.
list_dealsA
List deals from a saved view. Call list_views(module="deals") first to get a view_id (e.g. "Open Deals", "Won Deals").
Inputs: view_id (required), page, sort, per_page, +1 more.
list_field_choicesA
Look up a field's definition and valid dropdown choices (id -> label) for a module, including custom fields (cf_*). Use this before setting a dropdown/custom_field value you don't already know the id for — e.g. module="deals", field="deal_stage_id". IMPORTANT: for built-in fields (name has no cf_ prefix, e.g. deal_stage_id) pass the numeric id shown. For custom picklist fields (cf_* prefix) pass the label STRING (the "value" column) instead — the numeric id is silently ignored (200 response, no error, no change) for those.
Inputs: field (required), module (required).
list_leadsA
List leads from a saved view. Call list_views(module="leads") first to get a view_id.
Inputs: view_id (required), page, sort, per_page, +1 more.
list_ownersA
List all CRM users who can own leads/contacts/accounts/deals, with their owner_id.
Inputs: no named parameters.
list_tasksC
List tasks, optionally filtered.
Inputs: page, filter, per_page.
list_viewsA
List the saved views (filters) available for a module. A view id is required by list_contacts/list_accounts/list_deals/list_leads — call this first to get one (e.g. "All Contacts", "Open Deals", "My Leads").
Inputs: module (required).
searchC
Unified search across leads, contacts, accounts and deals by name/email/keyword.
Inputs: query (required), include.
search_accountsC
Search accounts (companies) by name/domain/keyword.
Inputs: query (required).
search_contactsC
Search contacts by name/email/keyword.
Inputs: query (required).
search_dealsC
Search deals by name/keyword.
Inputs: query (required).
search_leadsC
Search leads by name/email/company/keyword.
Inputs: query (required).
update_accountC
Update an existing account (company).
Inputs: account_id (required), city, name, tags, +12 more.
update_contactC
Update an existing contact.
Inputs: contact_id (required), city, tags, email, +12 more.
update_dealC
Update an existing deal (e.g. move to a new stage, change amount/owner).
Inputs: deal_id (required), name, tags, amount, +9 more.
update_leadC
Update an existing lead.
Inputs: lead_id (required), city, tags, email, +12 more.
update_taskB
Update a task, e.g. to reschedule, reassign, or mark it done. The exact accepted "status" value (e.g. "COMPLETED") hasn't been verified against this instance — check the result and adjust if rejected.
Inputs: task_id (required), title, status, due_date, +2 more.
view_accountC
View detailed information about an account (company).
Inputs: account_id (required).
view_contactA
View detailed information about a contact.
Inputs: contact_id (required).
view_dealC
View detailed information about a deal.
Inputs: deal_id (required).
view_leadC
View detailed information about a lead.
Inputs: lead_id (required).
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 30 tools
Most tools have clearly distinct purposes based on entity and action (e.g., create_lead, update_deal, search_contacts). However, the unified 'search' tool overlaps with the entity-specific search tools (search_leads, search_contacts, etc.), which could cause some confusion about which to use.
Tools predominantly follow a consistent verb_noun pattern (e.g., list_leads, create_contact, update_account). The only notable deviation is the standalone 'search' tool, which lacks a noun component, but otherwise the naming is predictable.
With 30 tools, the server is on the heavy side for its scope. While the tools are organized by entity, the sheer number (exceeding 25) may overwhelm an agent and increase selection complexity.
Core CRUD operations are covered for leads, contacts, accounts, and deals (create, read, update, list, search), but delete operations are entirely missing for all entities. This is a notable gap in the lifecycle, though agents can still manage most workflows.
Maintenance
Related MCP Connectors
API-first CRM for LLMs - contacts, companies, deals and activities over a native MCP server.
A CRM you talk to: leads, deals and a pipeline board inside ChatGPT, Grok and other MCP clients.
Open-source CRM: Claude, ChatGPT or any MCP client works with records, inbox and company knowledge.
Freshsales MCP server for ChatGPT, Claude and any AI agent: list rotten deals, move deal to another stage, mark deal won or lost, create task, add note, list overdue tasks, list contacts and list pipelines in your own Freshsales account. Cotlet works in the account through your Cloud Browser, a real Chrome where you sign in to Freshsales yourself; Cotlet does not store your password and you need no Freshsales API key. About the official Freshsales API: Yes, Freshsales has a full REST API, but no official MCP server for CRM data (checked 22 Oct 2026). You copy a personal API key from Profile Settings > API Settings and send it with every call, and Freshsales lists API access as a paid-plan feature. Setup and FAQ: https://cotlet.dev/integrations/freshsales-api-mcp-server
Related MCP Servers
- AlicenseNot gradedqualityCmaintenanceEnables AI agents to manage CRM data including companies, contacts, prospects, pipelines, forecasts, and tasks via typed MCP tools, with local SQLite storage and a JSON CLI.MIT
- AlicenseNot gradedqualityBmaintenanceProvides MCP tools to interact with GoHighLevel CRM data, including contacts, conversations, call transcripts, broker lead overviews, pipelines/opportunities, and task creation. Supports both stdio and HTTP transports for local and remote use.ISC
- FlicenseNot gradedqualityDmaintenanceAn MCP-native CRM backend for AI agents, enabling customer, opportunity, note, follow-up, and pipeline health management through 15 MCP tools.-
- FlicenseBqualityCmaintenanceEnables managing a small CRM of companies, contacts, deals, and activities through MCP tools, including creating and updating records, logging activities, searching across the CRM, and summarizing pipeline stages.15-