# pipedriver

**MCP server for the Pipedrive API v2.** Expose Pipedrive (deals, persons, organizations, products, activities, pipelines, and more) as tools to any [Model Context Protocol](https://modelcontextprotocol.io/) client—Cursor, Claude Desktop, and others.

Built with the official [Pipedrive JavaScript SDK](https://www.npmjs.com/package/pipedrive) and the [MCP TypeScript SDK](https://github.com/modelcontextprotocol/typescript-sdk).

---

## Quick start (npx)

No install. Run the server with your Pipedrive API token:

```bash
PIPEDRIVE_API_KEY=your_api_token npx pipedriver
```

Then point your MCP client at this command. Example for **Cursor** (Settings → MCP → Edit config):

```json
{
  "mcpServers": {
    "pipedriver": {
      "command": "npx",
      "args": ["-y", "pipedriver"],
      "env": {
        "PIPEDRIVE_API_KEY": "your_api_token"
      }
    }
  }
}
```

Get an API token in **Pipedrive → Settings → API**.

---

## Usage

### How it runs

The server uses **stdio transport**: your MCP client starts it as a subprocess and talks over stdin/stdout. No HTTP server or port.

### Option A: npx (recommended for trying it out)

```bash
npx -y pipedriver
```

Set `PIPEDRIVE_API_KEY` in the environment (or in your MCP config `env`, as in the example above).

### Option B: Install and run

```bash
npm install -g pipedriver
# or: yarn global add pipedriver

export PIPEDRIVE_API_KEY=your_api_token
pipedriver
```

### Option C: From a local clone (development)

```bash
git clone https://github.com/vaibhavpandeyvpz/pipedriver.git
cd pipedriver
yarn install
export PIPEDRIVE_API_KEY=your_api_token
yarn dev
```

In your MCP config, use the path to the repo:

```json
{
  "mcpServers": {
    "pipedriver": {
      "command": "node",
      "args": ["/path/to/pipedriver/dist/index.js"],
      "env": { "PIPEDRIVE_API_KEY": "your_api_token" }
    }
  }
}
```

Or without building (runs TypeScript with tsx):

```json
{
  "mcpServers": {
    "pipedriver": {
      "command": "npx",
      "args": ["tsx", "/path/to/pipedriver/src/index.ts"],
      "env": { "PIPEDRIVE_API_KEY": "your_api_token" }
    }
  }
}
```

### Tool naming

Tools follow `pipedrive_<domain>_<action>`, e.g. `pipedrive_deals_list`, `pipedrive_persons_add`. Arguments and request bodies match the [Pipedrive API v2](https://developers.pipedrive.com/docs/api/v2) (filters, sort, pagination, and JSON bodies where applicable).

---

## Tools overview

| Domain                  | Examples                                                                                                                                  |
| ----------------------- | ----------------------------------------------------------------------------------------------------------------------------------------- |
| **Activities**          | add, delete, list, get, update                                                                                                            |
| **Activity fields**     | get, list (metadata)                                                                                                                      |
| **Deals**               | add, delete, list, get, update, search; products (add/delete/update/many); followers; convert to lead; additional discounts; installments |
| **Deal fields**         | get, list (metadata)                                                                                                                      |
| **Item search**         | search, search by field                                                                                                                   |
| **Leads**               | search, convert to deal, get conversion status                                                                                            |
| **Organizations**       | add, delete, list, get, update, search; followers                                                                                         |
| **Organization fields** | get, list (metadata)                                                                                                                      |
| **Persons**             | add, delete, list, get, update, search; picture; followers                                                                                |
| **Person fields**       | get, list (metadata)                                                                                                                      |
| **Pipelines**           | add, delete, list, get, update                                                                                                            |
| **Products**            | add, delete, list, get, update, search; followers; duplicate; variations; image                                                           |
| **Product fields**      | get, list (metadata)                                                                                                                      |
| **Stages**              | add, delete, list, get, update                                                                                                            |
| **Users**               | get followers                                                                                                                             |

Each tool’s input schema in your MCP client describes parameters and optional fields.

---

## Development

### Prerequisites

- Node.js 18+
- Yarn (or npm)

### Setup

```bash
git clone https://github.com/vaibhavpandeyvpz/pipedriver.git
cd pipedriver
yarn install
```

Create a `.env` or export your token:

```bash
export PIPEDRIVE_API_KEY=your_api_token
```

### Commands

| Command      | Description                                        |
| ------------ | -------------------------------------------------- |
| `yarn dev`   | Run server from source (no build) via `tsx`        |
| `yarn build` | Compile TypeScript to `dist/`                      |
| `yarn start` | Run compiled server (`node dist/index.js`)         |
| `yarn test`  | Run Jest tests (start server, connect, list tools) |

### Project layout

- `src/` – Server entry, MCP server setup, Pipedrive client wrapper
- `src/tools/` – Tool handlers per domain (deals, persons, products, etc.)
- `src/schemas/` – Zod schemas for request bodies
- `tests/` – Integration tests (Jest)

---

## Deployment

This server is **not a long-lived HTTP service**. It is started by your MCP client when needed and communicates over stdio.

- **Production use** = your MCP client (e.g. Cursor, Claude Desktop) runs `npx pipedriver` or `pipedriver` with `PIPEDRIVE_API_KEY` set. No extra deployment step.
- **Publishing**: The package is published to npm via GitHub Actions on version tags (`v*`). See [.github/workflows/publish-npm.yml](.github/workflows/publish-npm.yml).

---

## License

MIT © [Vaibhav Pandey](https://github.com/vaibhavpandeyvpz)