Salesmate MCP Server

A production-ready Model Context Protocol (MCP) server that exposes the Salesmate CRM to Claude Desktop (and any other MCP client). Built with FastMCP, HTTPX, Pydantic, and python-dotenv.

It lets Claude search contacts, inspect and update deals, create tasks and notes, and review recent activity — all through clean, typed, validated tools.

---

Get started

There are two ways to install. Pick one.

Option A - One-click install (.mcpb, no terminal)

The cleanest end-user experience. Anyone can install with no clone, no virtualenv, no JSON editing - just a click and a form.

1. Download the .mcpb bundle for your platform from the project's GitHub Releases page (or build it yourself - see below).
2. In Claude Desktop, go to Settings -> Extensions -> Install Extension... and pick the .mcpb file.
3. When prompted, enter:
   • Salesmate Session Key (the field is masked; stored in your OS keychain).
   • Salesmate Workspace URL, e.g. https://yourcompany.salesmate.io.
4. Done. No restart needed - the salesmate tools appear in the tool picker.

Use the Session Key. Salesmate shows three keys - Access Key, Secret Key, and Session Key (Setup -> Integrations -> API & Webhooks). The v4 API used here authenticates with the Session Key; the other two return AuthorizationFailed.

Build the bundle yourself

The .mcpb is platform-specific (Python wheels contain compiled binaries), so build it on the OS you'll install it on:

git clone https://github.com/arnav-chauhan-kgpian/salesmate-mcp.git
cd salesmate-mcp
python -m venv .venv
# Windows:  .\.venv\Scripts\activate     macOS/Linux:  source .venv/bin/activate
pip install -e .
python build_mcpb.py
# Output: dist/salesmate-mcp-<platform>-py<ver>.mcpb

Then install the resulting .mcpb as in step 2 above.

---

Option B - Clone & connect (manual)

A new user with no copy of the code connects in four steps:

# 1. Clone the repo
git clone https://github.com/arnav-chauhan-kgpian/salesmate-mcp.git
cd salesmate-mcp

# 2. Create a virtualenv and install
python -m venv .venv
# Windows:  .\.venv\Scripts\activate     macOS/Linux:  source .venv/bin/activate
pip install -e .

# 3. Connect to Claude Desktop (writes .env + Claude config, verifies live)
python setup_salesmate.py --verify

# 4. Fully quit and reopen Claude Desktop

You must provide your own secrets

This repository ships no credentials. Every user supplies their own Salesmate keys once. The setup_salesmate.py script will prompt for them and write them into a local .env file (which is git-ignored and never committed):

SALESMATE_API_KEY=<your Salesmate SESSION KEY>
SALESMATE_BASE_URL=https://yourcompany.salesmate.io

You can also create this .env by hand (copy .env.example to .env and fill it in) instead of letting the script prompt you — then run python setup_salesmate.py --no-input --verify.

Use the Session Key. Salesmate shows three keys — Access Key, Secret Key, and Session Key (Setup → Integrations → API & Webhooks). The v4 API used here authenticates with the Session Key; the other two return AuthorizationFailed.

The setup script:

1. Collects your Session Key + workspace URL (or reuses an existing .env).
2. Writes them to .env.
3. Registers the salesmate server in your Claude Desktop config — preserving any servers you already have, with a .bak backup. No secrets are written into the Claude config; the server reads them from your .env.
4. With --verify, runs a live read-only check so you know it works before opening Claude.

Non-interactive form (e.g. for scripted installs):

python setup_salesmate.py --api-key <SESSION_KEY> --base-url https://yourcompany.salesmate.io --verify

---

Features

• 🔌 8 MCP tools covering contacts, deals, tasks, notes and activities.
• 🧱 Modular architecture — config, client, models and exceptions are cleanly separated; each tool group lives in its own module.
• 🔁 Resilient HTTP client — async HTTPX with a 30s timeout, automatic retries and exponential backoff (honouring Retry-After) for transient 429/5xx/network failures.
• 🧪 Typed Pydantic models for every resource; structured JSON is always returned — never raw HTTP responses.
• 🛡️ Robust error handling — every failure is mapped to a structured error object (SalesmateAuthError, SalesmateNotFoundError, ...).
• 🪵 Structured logging to stderr (stdout is reserved for the MCP transport).
• ✅ Full unit-test suite covering every tool and the HTTP client.

---

Tools

Tool	Signature	Description
search_contacts	(query: str)	Search contacts by name, email or company.
get_contact	(contact_id: int)	Fetch a contact's full details.
list_deals	(contact_id: int | None)	List deals, optionally for one contact.
get_deal	(deal_id: int)	Fetch a deal's full details.
update_deal_stage	(deal_id: int, stage: str)	Move a deal to a new stage.
create_task	(title: str, due_date: str, contact_id: int | None)	Create a task.
create_note	(contact_id: int, note: str)	Attach a note to a contact.
get_recent_activities	(contact_id: int)	Recent activities for a contact.

Every tool returns a JSON object. On success the payload contains "ok": true plus the requested data; on failure it contains "error": true with a type and message (and status_code for API errors).

---

Project structure

salesmate-mcp/
├── server.py                         # FastMCP entrypoint
├── salesmate/
│   ├── __init__.py
│   ├── config.py                     # env loading + validation
│   ├── client.py                     # async HTTPX client (retries, errors)
│   ├── models.py                     # Pydantic response models
│   └── exceptions.py                 # exception hierarchy
├── tools/
│   ├── __init__.py                   # registration + error mapping
│   ├── contacts.py
│   ├── deals.py
│   ├── tasks.py
│   ├── notes.py
│   └── activities.py
├── tests/                            # pytest suite (tools + client + config)
├── .env.example
├── pyproject.toml
├── README.md
└── claude_desktop_config_example.json

---

Installation

1. Prerequisites

• Python 3.12+
• A Salesmate account with an API Session Key (Setup → Integrations → API & Webhooks). Salesmate shows three keys — Access Key, Secret Key and Session Key — and the v4 API used here authenticates with the Session Key.

2. Get the code

cd salesmate-mcp

3. Create and activate a virtual environment

macOS / Linux:

python3.12 -m venv .venv
source .venv/bin/activate

Windows (PowerShell):

py -3.12 -m venv .venv
.\.venv\Scripts\Activate.ps1

4. Install dependencies

# runtime only
pip install -e .

# runtime + dev/test tools
pip install -e ".[dev]"

Prefer not to install the project as a package? You can instead run: pip install mcp httpx pydantic python-dotenv

5. Configure environment variables

Copy the example file and fill in your credentials:

macOS / Linux:

cp .env.example .env

Windows (PowerShell):

Copy-Item .env.example .env

Then edit .env:

SALESMATE_API_KEY=your-salesmate-access-token
SALESMATE_BASE_URL=https://yourcompany.salesmate.io

All other variables are optional — see .env.example for the full list.

6. Run the server

python server.py

The server communicates over stdio. When launched manually it will simply wait for an MCP client to connect; logs are printed to stderr. Use the Claude Desktop integration below for normal use.

---

Claude Desktop integration

1. Locate your Claude Desktop config file:

   • macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
   • Windows: %APPDATA%\Claude\claude_desktop_config.json

2. Add the Salesmate server (see claude_desktop_config_example.json):

   {
     "mcpServers": {
       "salesmate": {
         "command": "python",
         "args": ["C:\\absolute\\path\\to\\salesmate-mcp\\server.py"],
         "env": {
           "SALESMATE_API_KEY": "your-salesmate-access-token",
           "SALESMATE_BASE_URL": "https://yourcompany.salesmate.io"
         }
       }
     }
   }
   

   Notes:

   • Use the absolute path to server.py.
   • If you use a virtual environment, point command at that env's Python (e.g. C:\\path\\to\\salesmate-mcp\\.venv\\Scripts\\python.exe on Windows or /path/to/salesmate-mcp/.venv/bin/python on macOS/Linux).
   • Credentials can be supplied either via the env block above or via a .env file next to server.py.

3. Restart Claude Desktop. The Salesmate tools will appear in the tool picker.

---

Usage examples (in Claude)

• "Search Salesmate for contacts at Acme."
• "Show me deals for contact 1024."
• "Move deal 555 to the Negotiation stage."
• "Create a task to follow up with contact 1024 due 2026-07-01."
• "Add a note to contact 1024: spoke with procurement, decision by Q3."
• "What are the recent activities for contact 1024?"

---

Configuration reference

Variable	Required	Default	Description
SALESMATE_API_KEY	✅	—	Salesmate Session Key (not the Access/Secret key).
SALESMATE_BASE_URL	✅	—	Workspace base URL (https://...).
SALESMATE_AUTH_HEADER		accessToken	Auth header name.
SALESMATE_LINKNAME		derived from base_url	Value for the required x-linkname header.
SALESMATE_TIMEOUT		30	Per-request timeout (seconds).
SALESMATE_MAX_RETRIES		3	Retry attempts for transient errors.
SALESMATE_BACKOFF_FACTOR		0.5	Base backoff delay (seconds).
SALESMATE_LOG_LEVEL		INFO	Logging verbosity.

---

Running the tests

pip install -e ".[dev]"
pytest

The suite uses pytest-asyncio and an in-memory httpx.MockTransport, so it runs fully offline and never touches the real Salesmate API.

---

Adapting to your Salesmate API version

Salesmate exposes several API versions and the exact endpoint paths and search payloads can differ between workspaces. All endpoint paths are centralised in salesmate/client.py in the ENDPOINTS dictionary, and the request bodies for search operations are small and self-contained — adjust them there if your workspace expects a different shape. The auth header name can be changed without code edits via SALESMATE_AUTH_HEADER.

---

License

MIT