# freshsales-mcp

A small [MCP](https://modelcontextprotocol.io) server that lets an AI
assistant (Claude, or any other MCP-compatible client) fetch and query data
from [Freshsales](https://www.freshworks.com/crm/sales/) CRM — leads,
contacts, deals, and accounts — directly in conversation.

The Freshsales API can do a lot more than this (creating/updating/deleting
records, managing tasks, webhooks, bulk operations, etc.). This server is
**deliberately read-only** — every tool issues a `GET` request and nothing
else touches your CRM data. That scope is intentional, not a limitation of
the API: it's easy to extend with write tools later if you decide you want
an assistant that can also create leads, update deal stages, log activities,
and so on, but for now it only ever reads.

## Setup

```bash
npm install
npm run build
```

Copy `.env.example` to `.env` and fill in your Freshsales bundle domain and
API key (Admin Settings > API Settings in Freshsales), or set the same two
variables in your MCP client config instead of a `.env` file.

## Tools

- `freshsales_search` — global search by name/email/phone/company across leads, contacts, deals, accounts.
- `freshsales_list_views` — list saved views/filters for a module (e.g. "Open Deals").
- `freshsales_list_records` — paginated list of records within a saved view.
- `freshsales_get_record` — fetch a single lead/contact/deal/account by id.
- `freshsales_raw_request` — escape hatch for any other GET endpoint under `/crm/sales/api`.

## Register with Claude Code

```bash
claude mcp add freshsales -- node "/Users/apple/aevy resource/freshsales mcp/dist/index.js"
```

Or add to your MCP config JSON directly:

```json
{
  "mcpServers": {
    "freshsales": {
      "command": "node",
      "args": ["/Users/apple/aevy resource/freshsales mcp/dist/index.js"],
      "env": {
        "FRESHSALES_DOMAIN": "aevytv.myfreshworks.com",
        "FRESHSALES_API_KEY": "your-api-key"
      }
    }
  }
}
```

Restart Claude Code / Claude Desktop after registering so it picks up the new server.

## Security

- Never commit `.env` — it holds your Freshsales API key. It's already
  gitignored; only `.env.example` (a blank template) is tracked.
- The API key is sent only to your own Freshsales domain, over HTTPS.
- All tools are read-only `GET` requests — this server cannot create,
  update, or delete anything in your CRM.

## License

MIT — see [LICENSE](LICENSE).