io.github.fernandoludvig/rdstation-crm-mcp
Manage RD Station CRM contacts, deals, tasks and notes, with pipeline health reports
Open source Open in the app JSON README (API)
About
Manage RD Station CRM contacts, deals, tasks and notes, with pipeline health reports
Details
- Kind
- MCP servers
- Topic
- Government & public data
- Publisher
- fernandoludvig
- Origin
- official
- Category
- ferramentas
- Transport
- local
- Version
- 0.2.0
- Last push
- 2026-08-05T22:16:07Z
- Repository state
- ativo
- Language
- TypeScript
- License
- MIT
- Added
- 2026-08-29 03:02:47
- Updated
- 2026-08-29 03:02:47
- Origin id
io.github.fernandoludvig/rdstation-crm-mcp
README
# rdstation-crm-mcp
[](https://github.com/fernandoludvig/rdstation-crm-mcp/actions/workflows/ci.yml)
[](https://www.npmjs.com/package/rdstation-crm-mcp)
[](LICENSE)
An open-source **[MCP](https://modelcontextprotocol.io) server for [RD Station CRM](https://crm.rdstation.com)** — the leading CRM in Brazil and Latin America. Manage contacts, deals, tasks and notes, and get pipeline health reports, straight from Claude or any MCP-compatible client.
> "How's my sales pipeline this month?" → stage-by-stage totals, win rate, and the deals going stale.
## Why
RD Station CRM is huge in the LatAm market, but had no open-source MCP server. This project connects it to the MCP ecosystem so AI agents can work your pipeline: qualifying leads, moving deals, scheduling follow-ups, and answering questions about your sales data in natural language.
## Quick start
1. Get your **instance token** in RD Station CRM: *Profile → Products and integrations → Instance token*.
2. Add the server to your MCP client.
**Claude Desktop** (`claude_desktop_config.json`):
```json
{
"mcpServers": {
"rdstation-crm": {
"command": "npx",
"args": ["-y", "rdstation-crm-mcp"],
"env": {
"RDSTATION_CRM_TOKEN": "your-instance-token"
}
}
}
}
```
**Claude Code:**
```bash
claude mcp add rdstation-crm -e RDSTATION_CRM_TOKEN=your-instance-token -- npx -y rdstation-crm-mcp
```
That's it. Ask Claude something like *"list my open deals"* or *"give me a pipeline overview"*.
## Tools
| Tool | Description |
| --- | --- |
| `rdcrm_search_contacts` | Search contacts by name, email or phone |
| `rdcrm_get_contact` | Contact details, including linked deals |
| `rdcrm_upsert_contact` | Create a contact, or update it if the email already exists |
| `rdcrm_list_deals` | List deals filtered by status, pipeline, stage, owner, dates |
| `rdcrm_get_deal` | Deal details: stage, value, owner, contacts, products |
| `rdcrm_create_deal` | Create a deal — accepts stage by *name*, resolved automatically |
| `rdcrm_update_deal` | Move stage, change owner, rating, close date, pause/resume |
| `rdcrm_close_deal` | Mark won or lost (lost reasons resolved by name) |
| `rdcrm_list_tasks` | List tasks by deal, assignee, status, type, due date |
| `rdcrm_create_task` | Create a task (call, email, meeting, whatsapp...) on a deal |
| `rdcrm_add_note` | Add a note to a deal's timeline |
| `rdcrm_pipeline_overview` | Pipeline health report: totals per stage, win rate, stalled deals |
### Design notes
These tools are designed for LLMs, not as a 1:1 API wrapper:
- **Names instead of IDs.** Stages, pipelines, users and lost reasons can be passed by name; the server resolves them against the account and lists the valid options when something doesn't match.
- **Compact responses.** List tools return one line per record with the fields that matter, plus explicit pagination hints. Large responses are truncated with guidance instead of flooding the context window.
- **Actionable errors.** A 401 tells you which env var to check; an unknown stage lists every stage in every pipeline.
- **Aggregation where it counts.** `rdcrm_pipeline_overview` answers the questions humans actually ask ("where are deals stuck?") with a single tool call.
## Remote deployments (Streamable HTTP)
The default (`rdstation-crm-mcp`) runs over stdio for a single local user, with the token read once from `RDSTATION_CRM_TOKEN`. For a team-hosted or registry-listed deployment (e.g. Smithery), run the Streamable HTTP variant instead:
```bash
npx -y rdstation-crm-mcp-http
```
This starts an HTTP server (`http://127.0.0.1:8080/mcp` by default) implementing the [MCP Streamable HTTP transport](https://modelcontextprotocol.io/specification/2025-06-18/basic/transports#streamable-http), with proper session lifecycle (`initialize` → `Mcp-Session-Id` → `DELETE` to close).
Because a hosted server can serve more than one user, there's no single implicit token: each session sends its own `Authorization: Bearer <token>` header on `initialize`. A `RDSTATION_CRM_TOKEN` env var still works as a fallback default for a single-tenant self-hosted setup where every caller shares one CRM account.
Env vars:
| Var | Default | Purpose |
| --- | --- | --- |
| `PORT` | `8080` | Port to listen on |
| `HOST` | `127.0.0.1` | Bind address — use `0.0.0.0` for containers/cloud |
| `ALLOWED_HOSTS` | *(unset)* | Comma-separated Host header allow-list (DNS-rebinding guard); recommended when binding to `0.0.0.0` without a reverse proxy in front |
| `RDSTATION_CRM_TOKEN` | *(unset)* | Default token used when a session sends no Authorization header |
```bash
curl http://127.0.0.1:8080/health
# {"status":"ok","server":"rdstation-crm-mcp","sessions":0}
```
## Development
```bash
git clone https://github.com/fernandoludvig/rdstation-crm-mcp.git
cd rdstation-crm-mcp
npm install
npm test # unit tests (API mocked with msw)
npm run typecheck
npm run build
RDSTATION_CRM_TOKEN=xxx npx @modelcontextprotocol/inspector node dist/index.js
```
The HTTP layer (`src/client/`) is isolated from the tools, with retry and exponential backoff for 429/5xx built in.
## Roadmap
- [ ] Organizations and products tools
- [ ] RD Station CRM API v2 support (OAuth) behind the same tool surface
- [x] Streamable HTTP transport for remote deployments
- [ ] Publish to MCP registries (Glama, PulseMCP, Smithery)
Contributions welcome — open an issue first for anything non-trivial.
## License
[MIT](LICENSE) © Fernando Ludvig
*Not affiliated with or endorsed by RD Station. Uses the public [RD Station CRM API v1](https://developers.rdstation.com/reference/crm-v1-introducao-e-requisitos).*