Raynet MCP Server

Raynet CRM MCP服务器

   ](CHANGELOG.md) 

模型上下文协议（MCP）服务器，提供Claude AI和Raynet CRM之间的无缝集成，通过自然语言交互实现AI驱动的CRM操作。

v0.80.0（2026-02-09）： 移动模式——现场销售代表必备的25个工具（默认）。集 TOOL_MODE=full 所有91种工具。看 更改日志.md.

概述

此MCP服务器将Claude AI与Raynet CRM系统连接起来，允许用户通过Claude Desktop、Telegram机器人或n8n工作流等对话界面执行CRM操作。专为讲波兰语的团队设计，支持当地业务工作流程。

主要特点

• 自然语言CRM运营：通过对话式人工智能管理公司、联系人、交易、活动、潜在客户、产品、报价、销售订单和项目
• 波兰语支持：具有适当发音符号处理的本地波兰语界面
• 91 MCP工具：全面覆盖CRM工作流程，包括销售渠道、报价和项目管理
• 移动模式（默认）：现场销售代表的25个基本工具——减少LLM背景，专注于现场相关行动
• 双重运输：stdio（克劳德桌面）和HTTP/JSON-RPC（n8n、Telegram、远程部署）
• 承载令牌认证：使用安全的HTTP传输 MCP_API_KEY 认证
• 企业就绪：速率限制、错误处理、具有指数回退的重试逻辑
• 克劳德桌面兼容：适用于Claude Desktop MCP配置

可用工具（共91个）

公司（Firmy）-6个工具

公司地址（地址公司）-5工具（新）

非接触式（接触式）-7个工具

联系人关系 - 5 Tools （NEW）

产品（生产）-7个工具（新）

交易（销售机会） - 8 Tools

优惠（Oferty）-9个工具（新）

销售订单 - 10 Tools （NEW）

项目 (项目) - 8 工具 (新)

活动（Aktywnosci）-9个工具

Lead（Leady）-9个工具

Enums （字典） - 8 Tools

快速开始

先决条件

• Node.js 18+和npm
• 具有API访问权限的Raynet CRM帐户
• API凭据（用户名、API密钥、实例名称）

安装

# Clone the repository
git clone https://github.com/AiPulseInc/raynet-mcp-server.git
cd raynet-mcp-server

# Install dependencies
npm install

# Copy environment template
cp .env.example .env

# Configure your credentials
nano .env

配置

创建一个 .env 使用您的Raynet凭据文件：

# Required Configuration
RAYNET_INSTANCE_URL=https://app.raynet.cz/api/v2
RAYNET_INSTANCE_NAME=your-crm-instance
RAYNET_USERNAME=your-email@domain.com
RAYNET_API_KEY=your-api-key-here

# Server Configuration
PORT=3000
NODE_ENV=development
LOG_LEVEL=info
LOG_FORMAT=pretty

# Tool Mode: 'mobile' (25 tools, default) or 'full' (all 91 tools)
TOOL_MODE=mobile

# HTTP Transport Authentication (optional, for remote deployment)
# MCP_API_KEY=your-bearer-token-here

查找您的凭据

1. 实例URL：根据您的地区选择：

- 捷克的： https://app.raynet.cz/api/v2 - 斯洛伐克语： https://app.raynetcrm.sk/api/v2 - 国际： https://app.raynetcrm.com/api/v2

1. 实例名称：您的CRM实例标识符（在您的Raynet URL中找到）

1. API密钥：在Raynet CRM中的“设置”->“API密钥”下生成

运行服务器

# Development mode (stdio transport — for Claude Desktop)
npm run dev

# Development mode (HTTP transport — for n8n, Telegram, remote)
npm run dev:http

# Production build
npm run build

# Start HTTP server (default, for deployment)
npm start

# Start stdio server (for Claude Desktop)
npm run start:stdio

与Claude Desktop一起使用

添加到您的Claude Desktop MCP配置(~/.config/claude/claude_desktop_config.json):

{
  "mcpServers": {
    "raynet": {
      "command": "node",
      "args": ["/path/to/raynet-mcp-server/dist/index.js"],
      "env": {
        "RAYNET_INSTANCE_URL": "https://app.raynet.cz/api/v2",
        "RAYNET_INSTANCE_NAME": "your-instance",
        "RAYNET_USERNAME": "your-email",
        "RAYNET_API_KEY": "your-api-key"
      }
    }
  }
}

移动模式（面向现场销售代表的25个工具）

集 TOOL_MODE=mobile 仅展示25个针对移动端销售代表优化的基本工具（Claude、Telegram、n8n）。这减少了LLM上下文的使用，并使AI专注于与现场相关的操作。

{
  "mcpServers": {
    "raynet": {
      "command": "node",
      "args": ["/path/to/raynet-mcp-server/dist/index.js"],
      "env": {
        "TOOL_MODE": "mobile",
        "RAYNET_INSTANCE_URL": "https://app.raynet.cz/api/v2",
        "RAYNET_INSTANCE_NAME": "your-instance",
        "RAYNET_USERNAME": "your-email",
        "RAYNET_API_KEY": "your-api-key"
      }
    }
  }
}

移动工具包括：

不包括在移动模式中： 删除操作、地址管理、联系人关系、销售订单、项目、单个枚举查找和批量更新操作。这些在以下情况下仍然可用 TOOL_MODE=full.

对话示例（波兰语）

创建公司：

User: "Dodaj nowa firme TEST Sp. z o.o. z ocena A"
Assistant: [Uses raynet_create_company]
Response: "Utworzono firme TEST Sp. z o.o. (ID: 12345) z ocena A"

检查管道：

User: "Jaka jest wartosc naszego pipeline?"
Assistant: [Uses raynet_get_pipeline_value]
Response: "Wartosc Pipeline
- Liczba aktywnych szans: 4
- Laczna wartosc: 42 000 zl
- Wartosc wazona: 21 000 zl"

创建报价：

User: "Stworz oferte dla firmy ABC z produktem X za 5000 zl"
Assistant: [Uses raynet_create_offer_with_items]
Response: "Oferta utworzona pomyslnie!
**Oferta ABC - Produkt X** (ID: 456)
- Status: Aktywna
- Wartosc: 5 000.00 PLN"

管理项目：

User: "Pokaz aktywne projekty"
Assistant: [Uses raynet_list_projects with status filter]
Response: "Znaleziono 3 projektow:
**Wdrozenie CRM** (ID: 789)
- Status: Aktywny
- Firma: ABC Sp. z o.o.
- Okres: 2026-01-01 - 2026-03-31"

与潜在客户合作：

User: "Pokaz statystyki leadow"
Assistant: [Uses raynet_get_lead_stats]
Response: "Statystyki Leadow
- Lacznie: 15
- Aktywne: 8
- Skonwertowane: 5
- Anulowane: 2"

项目结构

raynet-mcp-server/
├── src/
│   ├── index.ts              # Entry point (stdio transport)
│   ├── server.ts             # MCP server (stdio)
│   ├── server-http.ts        # MCP server (HTTP/JSON-RPC)
│   ├── version.ts            # Centralized version constant
│   ├── config/
│   │   └── env.ts            # Environment configuration + Zod validation
│   ├── api/
│   │   ├── client.ts         # Raynet API client (auth, retries, rate limiting)
│   │   ├── companies.ts      # Companies service
│   │   ├── contacts.ts       # Contacts service
│   │   ├── deals.ts          # Deals service
│   │   ├── activities.ts     # Activities service
│   │   ├── leads.ts          # Leads service
│   │   ├── products.ts       # Products service
│   │   ├── offers.ts         # Offers service
│   │   ├── salesOrders.ts    # Sales orders service
│   │   ├── projects.ts       # Projects service
│   │   └── enums.ts          # Enums/lookups service
│   ├── tools/
│   │   ├── index.ts          # Tool registry, mobile filter, router
│   │   ├── companies.ts      # Company & address MCP tools
│   │   ├── contacts.ts       # Contact & relationship MCP tools
│   │   ├── deals.ts          # Deal MCP tools
│   │   ├── activities.ts     # Activity MCP tools
│   │   ├── leads.ts          # Lead MCP tools
│   │   ├── products.ts       # Product MCP tools
│   │   ├── offers.ts         # Offer MCP tools
│   │   ├── salesOrders.ts    # Sales order MCP tools
│   │   ├── projects.ts       # Project MCP tools
│   │   └── enums.ts          # Enum MCP tools
│   ├── utils/
│   │   ├── logger.ts         # Winston logger with sensitive data redaction
│   │   └── errors.ts         # Error classes with Polish messages
│   └── types/
│       └── index.ts          # TypeScript types
├── tests/
│   └── unit/                 # Unit tests (Vitest)
├── docs/
│   ├── RAYNET-API.md         # API documentation
│   └── TEST_REPORT.md        # Integration test results
├── .env.example              # Environment template
├── CHANGELOG.md              # Release history
├── TODO.md                   # Development roadmap
├── package.json
├── tsconfig.json
└── README.md

速率限制

服务器执行速率限制以符合Raynet API的限制：

• 每日限额：每天24000个请求
• 并发限制：最多4个并发连接
• 自动重试：对429个错误进行指数回退的自动重试

每个请求都会跟踪并记录速率限制标头。

安全

• 基本认证：每个Raynet API请求都使用用户名+API密钥
• 承载令牌认证：HTTP传输受保护 MCP_API_KEY 环境变量
• 实例标头: X-Instance-Name 与每个API调用一起发送的头
• 凭据存储：所有凭据都通过环境变量（从未硬编码）
• 输入验证：Zod模式在API调用之前验证所有工具输入
• 日志重设：从日志中自动编辑的敏感字段（API密钥、令牌、密码）

HTTP传输

对于远程部署（Railway、n8n、Telegram机器人），服务器提供HTTP/JSON-RPC传输：

# Set authentication token
export MCP_API_KEY=your-secret-bearer-token

# Start HTTP server
npm start

终点：

请求示例：

curl -X POST http://localhost:3000/mcp \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer your-secret-bearer-token" \
  -d '{"jsonrpc":"2.0","method":"tools/list","id":1}'

发展

# Build the project
npm run build

# Run unit tests
npm test

# Run tests in watch mode
npm run test:watch

# Type check
npm run type-check

# Lint
npm run lint

# Format code
npm run format

测试

# Unit tests (Vitest)
npm test

# With coverage
npm run test:coverage

# Integration tests (requires Raynet credentials)
npm run test:integration

看 docs/TEST_REPORT.md 查看详细的集成测试结果。

故障排除

问题：“缺少X-Instance-Name标头”

# Ensure RAYNET_INSTANCE_NAME is set in .env

问题：“超出费率限制（429）”

# Server auto-retries. Check daily usage (24,000 requests/day limit)

问题：“连接超时”

# Increase timeout in config or check network connectivity

问题：“日期格式错误”

# Raynet expects dates in YYYY-MM-DD HH:mm format, not ISO 8601

许可证

此项目根据MIT许可证获得许可-请参阅 许可证 文件以获取详细信息。

致谢

• Raynet CRM 用于CRM平台和API
• Anthropic 用于Claude AI和MCP协议
• 模型上下文协议 社区

______________________________________________________________________

专为波兰CRM团队打造 | 由Claude AI+MCP提供技术支持