# Raynet CRM — MCP Connector for Claude

Connect [Claude](https://claude.ai) directly to your [Raynet CRM](https://raynet.cz).
Search records, create leads and business cases, and manage your sales pipeline
by chatting with Claude — no copy-pasting, no switching tabs.

Install it in **one click**. No terminal, no Node.js, no Python, no config files.

---

## What it does

Once installed, Claude can work with your Raynet CRM through 11 tools:

**Reading**
- Test the connection and see your record counts
- Search leads, business cases, companies, and people — with field filters,
  full-text search, paging, and newest-first ordering
- Fetch full details of any record
- Read your CRM's own categories, sources, phases, and business-case types
  (the connector reads *your* instance's values live — it never assumes names)
- Scan your CRM's structure

**Creating**
- Create a lead with contact details
- Convert a lead into a business case
- Create a full pipeline (company → person → lead → business case) in one step

**Deleting**
- Delete a record — with a **built-in safeguard**: you must type the record's
  exact code (or name) to confirm, so nothing is deleted by accident.

---

## Install

1. **Download** the latest `raynet-mcp-*.mcpb` file from the
   [Releases](../../releases) page.
2. **Open Claude Desktop** → Settings → Extensions → *drag the `.mcpb` file in*
   (or double-click the file).
3. **Enter your Raynet details** in the window that appears:
   - **Instance name** — your Raynet account name
   - **Login** — the email you sign in to Raynet with
   - **API key** — from Raynet (stored securely in your system keychain)
   - **Default owner ID** — *(optional)* the user ID that will own records the
     connector creates; only needed if you create records
4. **Enable** the extension and restart Claude Desktop.
5. Open a new chat and try: *"Test the Raynet connection and tell me how many
   leads I have."*

Works on **macOS, Windows, and Linux** (Claude Desktop, all plans including Free).
Heavy use may need a paid plan due to message limits.

### Where do I find my API key?

In Raynet, under your account/API settings. The connector uses your login email
plus this key to authenticate — the same credentials your own Raynet account has,
so it can only see and do what you can.

---

## Using with other MCP clients

This connector speaks the standard **Model Context Protocol over stdio**, so it is
**not Claude-only**. Any MCP client that can launch a local stdio server can use all
11 Raynet tools — no code changes, no separate build. The same `dist/index.js` and the
same four environment variables that power the Claude Desktop `.mcpb` work everywhere.

Verified setups below: **Google Gemini CLI** and **DeepSeek Harness (dsh)**.

### Prerequisites

Unlike the `.mcpb` (which ships with everything Claude Desktop needs), these clients
launch the server themselves with your system's Node, so you need:

- **Node.js** installed (LTS recommended)
- The server's built `dist/index.js` on disk — get it in one of two ways:

**Option A — clone & build (canonical):**

```bash
git clone https://github.com/leomatix/raynet-mcp.git
cd raynet-mcp
npm install
npm run build          # produces dist/index.js
```

**Option B — reuse the `.mcpb` you already downloaded (shortcut):**
A `.mcpb` file is just a zip. Unpack it and you already have `dist/` plus its
dependencies — no build step needed:

```bash
unzip raynet-mcp-0.2.0.mcpb -d raynet-mcp-unpacked
# dist/index.js now lives in raynet-mcp-unpacked/dist/
```

Either way, note the **absolute path** to `dist/index.js` — you'll paste it into the
config below.

You'll also need your Raynet credentials (see
[Where do I find my API key?](#where-do-i-find-my-api-key) in this README).

---

### Google Gemini CLI

Add the server to `~/.gemini/settings.json` (global) or `.gemini/settings.json` (per
project) under the `mcpServers` key:

```json
{
  "mcpServers": {
    "raynet": {
      "command": "node",
      "args": ["/absolute/path/to/raynet-mcp/dist/index.js"],
      "env": {
        "RAYNET_INSTANCE": "your-instance",
        "RAYNET_LOGIN": "you@example.com",
        "RAYNET_API_KEY": "$RAYNET_API_KEY",
        "RAYNET_DEFAULT_OWNER_ID": "1"
      }
    }
  }
}
```

Gemini CLI expands environment variables inside the `env` block, so keeping the key in
your shell (`export RAYNET_API_KEY=...`) rather than hard-coding it is the safer
choice. `RAYNET_DEFAULT_OWNER_ID` is optional.

**Verify:**

```bash
gemini mcp list        # "raynet" should appear
```

Then start `gemini` and run `/mcp` inside the CLI to see the server status and the
11 registered tools. Try: *"Run raynet_test_connection and tell me how many leads I
have."*

---

### DeepSeek Harness (dsh)

DeepSeek Harness ships an official MCP client plugin, `@deepseek-ai/dsh-mcp-client`.
One entry per server is the whole setup. Add it to your profile's `cordis.patch.yml`:

```yaml
- insert:
    - id: mcp-raynet
      name: '@deepseek-ai/dsh-mcp-client'
      config:
        serverName: raynet
        transport: stdio
        command: node
        args: ['/absolute/path/to/raynet-mcp/dist/index.js']
        env:
          RAYNET_INSTANCE: your-instance
          RAYNET_LOGIN: you@example.com
          RAYNET_API_KEY: !!js process.env.RAYNET_API_KEY
          RAYNET_DEFAULT_OWNER_ID: '1'
```

The `!!js process.env.RAYNET_API_KEY` tag reads the key from the environment at load
time instead of writing the secret into the file — export `RAYNET_API_KEY` in the shell
that launches `dsh`. After a restart, the tools appear namespaced as
`mcp__raynet__raynet_search`, `mcp__raynet__raynet_test_connection`, and so on.

**Verify:** in a chat, ask *"Run mcp__raynet__raynet_test_connection and tell me how
many leads I have."*

> **Note:** DeepSeek Harness is in developer preview; its plugin config schema can shift
> between releases. If a future `dsh` upgrade changes the `dsh-mcp-client` schema,
> re-check with `dsh --dump-config`.

---

### A note on ChatGPT and remote clients

The setups above work because Gemini CLI and dsh run the server **locally over stdio**.
Clients that only connect to **remote** MCP servers over HTTPS (e.g. ChatGPT) need a
different transport (Streamable HTTP), a hosted endpoint, and authentication — that's on
the roadmap, not part of this stdio guide.

## Privacy — please read

This connector is a **local bridge** between Claude Desktop (on your computer)
and your Raynet CRM. Here's what that means for your data:

- **The connector itself sends your data nowhere.** It has no telemetry, no
  "phone home", no external logging. It talks only to Raynet's API, using your
  own credentials. The source code is public — you can verify this.
- **Your API key stays on your machine**, in your operating system's secure
  keychain (macOS Keychain / Windows Credential Manager). It is never written to
  a file or included in the package.
- **Data reaches an AI model only when you ask.** When you ask Claude a question,
  Claude pulls just what's needed to answer it — not your whole database. There
  is no bulk upload of your CRM.

**Where the connector's responsibility ends:** once data is in your conversation,
what happens to it is governed by **your AI provider's policy** (Anthropic, or
whichever model you use), not by this connector. Review your provider's data and
retention policy to understand how conversation data is handled.

**Want maximum privacy?** Because this is a standard MCP server, you can point it
at a **locally-run model** instead of a cloud AI. In that setup your CRM data
never leaves your own infrastructure at all.

---

## Important notes

- **Use at your own risk.** This is free, open-source software provided as-is
  (see LICENSE). It creates and **deletes** real records in your CRM. **Test on
  non-production or test data first** before relying on it for real work.
- **Deletion is guarded** but still real — once confirmed, a record is gone.
- This is an independent, community project and is **not affiliated with or
  endorsed by Raynet** or Anthropic.

---

## Searching your CRM

`raynet_search` supports real filtering, so Claude can answer targeted questions
in a single query:

- **Field filters** using Raynet's operator syntax — `"field[OP]": value`, where
  `OP` is `GT`, `LT`, or `EQ` (a plain `"field": value` means equals). Works on
  dates and enum fields, e.g. leads created from 15 Aug onward:
  `{"leadDate[GT]": "2026-08-14"}`.
- **Full-text search** across a record type.
- **Paging** with `offset` alongside `limit`.
- **Newest-first** ordering via a `newest_first` flag.

A couple of Raynet quirks worth knowing (Claude handles them for you):
- Raynet supports `GT` / `LT` / `EQ` but **not** `>=` / `<=` — for an inclusive
  lower bound, use `GT` with the day before.
- Raynet's list endpoint has no sort parameter, so results default to creation
  order; `newest_first` is provided for when you want the most recent records.

See the issues page to report problems or request features.

---

## Related project

Running WordPress? There's a companion plugin by the same author that sends your
contact-form submissions straight to Raynet CRM as leads —
[raynet-lead-form](https://github.com/leomatix/raynet-lead-form). Also free and
open source.

## Support

This project is community-supported and shared freely as a thank-you to the
open-source community — please open an issue on GitHub for bugs and feature
requests. It's maintained in spare time, so please set expectations accordingly.
For other enquiries, including help with CRM automation or AI integration for
your business, contact **<kontakt@leomatix.net>**.

## License

MIT — see [LICENSE](LICENSE).

Raynet® and Raynet CRM® are trademarks of their respective owner. This is an
independent, unofficial integration and is not affiliated with or endorsed by
Raynet or Anthropic.

---

Built by Adam Chludziński (Leomatix) · [leomatix.net](https://leomatix.net)