Freshsales CRM — Model Context Protocol (MCP) Server

Connect your AI Assistants (Claude, Cursor, Windsurf) directly to your Freshsales CRM data.

Welcome to the Freshsales MCP Server! This open-source server implements the official Model Context Protocol, allowing any compatible AI agent to securely interact with your Freshsales CRM.

Instead of writing custom API scripts or manually exporting CSVs, you can now simply ask your AI:

"What deals are currently in the 'Negotiation' stage?" "Create a new contact for Jane Doe at Acme Corp and add a note saying we met at the conference." "Summarize all recent activity for the contact m.scott@dundermifflin.com."

✨ Enterprise-Ready Features

• Massive Tool Suite (75+ Tools): Full CRUD support for Contacts, Accounts, Deals, Tasks, Notes, Activities, Documents, and Products.

• Dynamic AI Discovery: Deep, strict inputSchema definitions ensure AI models instantly understand required fields, eliminating hallucinated API requests.

• Smart Rate Limiting: Built-in exponential backoff (via tenacity) handles HTTP 429 errors gracefully so your AI never crashes during bulk operations.

• Context-Window Protection: Automatic pagination caps prevent large CRM databases from overloading the AI's memory.

• Multiple Transports:

  • stdio: Seamless integration with AI IDEs (Cursor, Windsurf, Cline) and Desktop Apps (Claude).

  • streamable-http & sse: Built-in Starlette/Uvicorn support for scalable web deployments and agentic frameworks.

Related MCP server: MCP Salesforce Lite

🚀 Quickstart Guide

For Claude Desktop Users

1. Open your Claude Desktop configuration file:

   • Windows: %APPDATA%\Claude\claude_desktop_config.json

   • Mac: ~/Library/Application Support/Claude/claude_desktop_config.json

2. Add the Freshsales server configuration:

{
  "mcpServers": {
    "freshsales": {
      "command": "uv",
      "args": ["run", "python", "-m", "freshsales_mcp", "--transport", "stdio"],
      "env": {
        "FRESHSALES_API_KEY": "YOUR_FRESHSALES_API_KEY",
        "FRESHSALES_DOMAIN": "yourcompany" 
      },
      "cwd": "C:\\path\\to\\freshsales_mcp"
    }
  }
}

Note: Your FRESHSALES_DOMAIN should only be your subdomain (e.g., use acme instead of acme.myfreshworks.com).

3. Restart Claude Desktop. You will see the 🔌 plug icon indicating the tools are loaded!

⚙️ Developer Installation

If you want to run the server standalone, test it locally, or deploy it to the cloud:

Prerequisites:

• Python 3.12+

• uv (Recommended for ultra-fast dependency management)

# 1. Clone the repository
git clone https://github.com/YOUR_USERNAME/freshsales-mcp-server.git
cd freshsales-mcp-server

# 2. Set up environment variables
cp .env.example .env
# Edit .env and add your FRESHSALES_API_KEY and FRESHSALES_DOMAIN

# 3. Install the package
uv pip install -e .

# 4. Start the server (defaults to stdio)
python -m freshsales_mcp

🧪 Testing with the MCP Inspector

The MCP Inspector is the official interactive developer tool that lets you test all 75+ tools visually in your browser before you hook them up to an AI.

To run the inspector:

npx @modelcontextprotocol/inspector uv run python -m freshsales_mcp

1. The command will output a local URL (e.g., http://localhost:5173).

2. Open that URL in your browser and click Connect.

3. Navigate to the Tools tab to see the entire Freshsales integration.

4. Try clicking freshsales_get_selectors, enter deal_stages, and click Run to see real CRM data flow back!

🚝 Transport Modes

This server implements all three official MCP transport modes. You can switch between them using the --transport flag.

1. stdio (Default)

Best for: Local AI IDEs (Cursor, Windsurf, Cline) and Desktop Apps (Claude Desktop). How it works: The AI communicates with the server directly through standard input/output streams. It is incredibly fast and requires no networking.

python -m freshsales_mcp --transport stdio

2. streamable-http (Modern Web)

Best for: Cloud deployments, scalable architectures, and the OpenAI Agents SDK. How it works: The modern standard for running MCP servers over the internet. It uses standard HTTP requests and avoids the timeout issues of long-lived SSE connections.

# Starts a Uvicorn server on http://0.0.0.0:8080
python -m freshsales_mcp --transport streamable-http

Note: You can change the port by setting PORT=9090 in your .env file.

3. sse (Legacy Web)

Best for: Older frameworks that specifically require Server-Sent Events. How it works: Establishes a persistent, one-way connection from the server to the client using the /messages/ endpoint.

python -m freshsales_mcp --transport sse

🛠️ Tool Architecture

The server exposes modular toolsets. The AI will intelligently chain these tools together to accomplish complex tasks.

• Contacts & Accounts: Full lifecycle management, including bulk upserts, owner assignments, and timeline activity retrieval.

• Deals (Opportunities): Pipeline management, deal stage transitions, and CPQ document tracking.

• Intelligent Lookup: The freshsales_search and freshsales_list_filters tools allow the AI to dynamically find internal View IDs and UUIDs without user intervention.

• Files & Documents: Supports native multipart/form-data, allowing the AI to decode base64 strings and upload binary files/attachments directly to CRM records.

🤝 Contributing

We welcome community contributions! Whether you're fixing a bug, adding a new Freshsales endpoint, or optimizing the tool schemas for better AI reasoning, your help is appreciated.

Please see our Contributing Guidelines for details on how to set up your environment, our branching strategy (dev vs main), and how to submit a Pull Request.

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.