内容
# Elorus-MCP
Elorus 平台的 MCP 服务器。使 AI 助手能够创建发票、管理联系人并通过自然语言查询财务数据。
## 设置
### 先决条件
- Node.js 20+
- 具有 API 密钥和组织 ID 的 Elorus 账户
### 获取您的凭证
1. **API 密钥** — 打开 Elorus 网页应用 → 用户资料 → API 密钥
2. **组织 ID** — 打开 Elorus 网页应用 → 设置 → 组织 → 组织 ID
### 安装
```bash
npx elorus-mcp
```
或克隆并在本地构建：
```bash
git clone https://github.com/your-org/elorus-mcp
cd elorus-mcp
npm install && npm run build
```
## Claude Desktop 配置
添加到 `~/Library/Application Support/Claude/claude_desktop_config.json`（macOS）或 `%APPDATA%\Claude\claude_desktop_config.json`（Windows）：
```json
{
"mcpServers": {
"elorus": {
"command": "npx",
"args": ["elorus-mcp"],
"env": {
"ELORUS_API_KEY": "your-api-key",
"ELORUS_ORG_ID": "your-org-id"
}
}
}
}
```
## Claude 代码配置
```bash
claude mcp add elorus -e ELORUS_API_KEY=your-api-key -e ELORUS_ORG_ID=your-org-id -- npx elorus-mcp
```
### 本地开发
对于本地开发，`npm start` 从 `.env` 文件（通过 `node --env-file`）加载环境变量，而不是要求将它们作为内联参数传递。复制 `.env.example` 到 `.env` 并填写您的凭证：
```bash
cp .env.example .env
```
| 变量 | 必需 | 描述 |
|---|---|---|
| `ELORUS_API_KEY` | 是 | 您的 Elorus API 密钥 |
| `ELORUS_ORG_ID` | 是 | 您的 Elorus 组织 ID |
| `ELORUS_DEMO` | 否 | 设置为 `1` 以在所有请求上发送 `X-Elorus-Demo: 1`（针对 Elorus 的演示/沙箱环境） |
注意：如果服务器由具有自己的 `env` 块的 MCP 客户端配置（例如 Claude Desktop/Code）启动，则该 `env` 块优先，`.env` 不会被读取 — 只有 `npm start` 调用 `node --env-file=.env`。将凭证保存在一个地方，以避免两者静默分离。
## 可用工具
### 联系人
| 工具 | 描述 |
|---|---|
| `list_contacts` | 搜索/筛选联系人（客户、供应商或两者）并分页 |
| `get_contact` | 按 ID 获取联系人 |
| `create_contact` | 创建客户、供应商或两者 |
| `update_contact` | 更新现有联系人的字段 |
### 发票
| 工具 | 描述 |
|---|---|
| `list_invoices` | 按状态、客户、日期范围筛选发票 |
| `get_invoice` | 按 ID 获取发票 |
| `create_invoice` | 创建带有行项目和税款的销售发票 |
| `void_invoice` | 作废发票（从财务报告中排除，不能编辑或支付） |
| `send_invoice_email` | 将发票通过电子邮件发送给客户 |
| `export_invoice_pdf` | 将发票导出为 PDF（返回下载 URL） |
### 账单（供应商采购发票）
| 工具 | 描述 |
|---|---|
| `list_bills` | 按供应商、状态或日期范围筛选供应商账单 |
| `get_bill` | 按 ID 获取账单 |
| `create_bill` | 创建带有行项目和税款的供应商账单 |
| `update_bill` | 更新现有账单的字段 |
| `void_bill` | 作废账单 |
### 费用
| 工具 | 描述 |
|---|---|
| `list_expenses` | 按供应商、类别或日期范围筛选费用记录 |
| `get_expense` | 按 ID 获取费用 |
| `create_expense` | 记录新的商业费用。行项目使用 `expense_category`/`amount`/`description`（不是发票样式的 `title`/`quantity`/`unit_value`） |
| `update_expense` | 更新现有费用的字段 |
| `add_expense_attachment` | 将文件（例如收据或供应商发票 PDF）附加到现有费用，给定 base64 编码的内容 |
| `export_expense_pdf` | 将费用文档导出为 PDF（返回下载 URL） |
### 信用额度（发给客户）
| 工具 | 描述 |
|---|---|
| `list_credit_notes` | 按客户或日期范围筛选信用额度 |
| `create_credit_note` | 创建信用额度以减少或取消客户欠款 |
| `apply_credit_note` | 将信用额度应用于未结发票 |
### 供应商信用额度（从供应商收到）
| 工具 | 描述 |
|---|---|
| `list_supplier_credits` | 按供应商或日期范围筛选供应商信用额度 |
| `create_supplier_credit` | 记录从供应商收到的信用额度 |
| `apply_supplier_credit` | 将供应商信用额度应用于未结账单 |
### 现金收款（从客户收到付款）
| 工具 | 描述 |
|---|---|
| `list_cash_receipts` | 按客户、发票或日期范围筛选 |
| `record_cash_receipt` | 记录从客户收到的付款，可选链接到发票 |
| `export_cash_receipt_pdf` | 将现金收款导出为 PDF（返回下载 URL） |
### 现金付款（支付给供应商）
| 工具 | 描述 |
|---|---|
| `list_cash_payments` | 按供应商、账单或日期范围筛选 |
| `record_cash_payment` | 记录支付给供应商的付款，可选链接到账单 |
| `update_cash_payment` | 更新现有付款的字段（例如标题/银行参考） |
| `delete_cash_payment` | 永久删除支付给供应商的付款 |
### 产品
| 工具 | 描述 |
|---|---|
| `list_products` | 搜索产品/服务目录 |
| `get_product` | 按 ID 获取产品 |
| `create_product` | 将产品或服务添加到目录 |
| `update_product` | 更新现有产品或服务的字段 |
### 备注和讨论
| 工具 | 描述 |
|---|---|
| `list_private_notes` | 列出资源的内部备注（仅对组织成员可见） |
| `create_private_note` | 向资源添加内部备注 |
| `list_client_discussions` | 列出资源上的客户可见的讨论消息 |
| `create_client_discussion` | 在发票或现金收款上发布客户可见的消息 |
### 配置查找
| 工具 | 描述 |
|---|---|
| `list_taxes` | 列出组织中配置的税率 |
| `list_document_types` | 列出文档类型（创建发票、账单、信用额度等所需） |
| `list_units` | 列出测量单位（例如小时、件、千克） |
| `list_expense_categories` | 列出费用类别 |
## MCP 资源
只读资源，返回最多 100 条最新记录为 JSON，无需工具调用：
| 资源 URI | 描述 |
|---|---|
| `elorus://contacts` | 所有联系人（客户和供应商） |
| `elorus://invoices` | 所有销售发票，最近优先 |
| `elorus://cashreceipts` | 所有现金收款（从客户收到的付款） |
| `elorus://cashpayments` | 所有现金付款（支付给供应商的付款） |
| `elorus://expenses` | 所有费用记录 |
| `elorus://bills` | 所有供应商账单 |
| `elorus://products` | 目录中的所有产品和服务 |
## 示例提示
- *"为 Acme Corp 创建一张发票，5 小时咨询费，每小时 150 欧元，增值税 24%"*
- *"本月有哪些发票逾期？"*
- *"查找 Elorus FC 的联系人并显示其详细信息"*
- *"添加一个名为 'Website Design' 的新产品，价格 800 欧元，标准增值税"*
- *"记录 Staples 的 45 欧元办公用品费用"*
- *"有哪些供应商的账单逾期？"*
- *"将此信用额度应用于发票 #1042"*
## 备注
- 所有货币价值都是字符串（例如 `"1500.00"`），以避免浮点精度问题
- 使用 `list_taxes`、`list_document_types`、`list_units` 和 `list_expense_categories` 在创建发票、账单、费用、信用额度或产品之前查找有效 ID（账单不使用文档类型 — 只有发票、信用额度和估算使用）
- 发票/信用额度/供应商信用额度行项目使用 `title`/`quantity`/`unit_value`（或 `unit_total`，取决于 `calculator_mode`）；账单行项目还要求 `expense_category`；费用行项目使用不同的形状：`expense_category`/`amount`/`description`
- Elorus 不提供幂等键 — 在创建之前查询以避免重复
- 分页参数：`page`（默认 1）和 `page_size`（默认 20，最大 100）
