内容
# @honeyfield/sevdesk-mcp
sevDesk 账户管理服务器，为 sevDesk 财务 API 提供 52 种管理工具，包括联系人、发票、信用额度、订单、凭证、交易和库存等。
## 安装
```bash
npm install -g @honeyfield/sevdesk-mcp
```
或者直接使用 npx：
```bash
npx @honeyfield/sevdesk-mcp
```
## 配置
### 环境变量
将您的 sevDesk API 令牌设置为环境变量：
```bash
export SEVDESK_API_TOKEN=您的-api-令牌
```
### 获取 API 令牌
1. 登录您的 [sevDesk 账户](https://my.sevdesk.de)
2. 进入 **设置** (Einstellungen) → **用户** (Benutzer) → **API 令牌**
3. 生成一个新的令牌
4. 复制并安全存储该令牌（它只显示一次）
### Claude Desktop / Claude 代码
将以下内容添加到您的 MCP 配置中：
```json
{
"mcpServers": {
"sevdesk": {
"command": "npx",
"args": ["@honeyfield/sevdesk-mcp"],
"env": {
"SEVDESK_API_TOKEN": "您的-api-令牌"
}
}
}
}
```
## 可用工具（52 个）
### 联系人（8 个工具）
| 工具 | 描述 |
|------|-------------|
| `list_contacts` | 列出联系人，支持筛选（客户、供应商、合作伙伴） |
| `get_contact` | 按 ID 获取联系人详细信息 |
| `create_contact` | 创建新的联系人 |
| `update_contact` | 更新现有的联系人 |
| `delete_contact` | 删除联系人 |
| `get_next_customer_number` | 生成下一个客户编号 |
| `list_contact_addresses` | 列出联系人的地址 |
| `create_contact_address` | 创建新的联系人地址 |
### 发票（12 个工具）
| 工具 | 描述 |
|------|-------------|
| `list_invoices` | 列出发票，支持筛选 |
| `get_invoice` | 按 ID 获取发票详细信息 |
| `create_invoice` | 创建新的发票，包含项目 |
| `update_invoice` | 更新现有的发票 |
| `delete_invoice` | 删除发票 |
| `send_invoice_email` | 通过电子邮件发送发票 |
| `book_invoice_payment` | 为发票记录付款 |
| `enshrine_invoice` | 锁定/确认发票 |
| `reset_invoice_to_draft` | 将发票重置为草稿状态 |
| `get_invoice_pdf` | 获取发票 PDF 下载信息 |
| `export_invoice_xml` | 将发票导出为 XRechnung XML |
| `create_invoice_from_order` | 根据订单创建发票 |
### 信用额度（9 个工具）
| 工具 | 描述 |
|------|-------------|
| `list_credit_notes` | 列出信用额度，支持筛选 |
| `get_credit_note` | 按 ID 获取信用额度详细信息 |
| `create_credit_note` | 创建新的信用额度 |
| `update_credit_note` | 更新现有的信用额度 |
| `delete_credit_note` | 删除信用额度 |
| `send_credit_note_email` | 通过电子邮件发送信用额度 |
| `book_credit_note_payment` | 为信用额度记录付款 |
| `enshrine_credit_note` | 锁定/确认信用额度 |
| `create_credit_note_from_invoice` | 根据发票创建信用额度 |
### 订单（6 个工具）
| 工具 | 描述 |
|------|-------------|
| `list_orders` | 列出订单/报价，支持筛选 |
| `get_order` | 按 ID 获取订单详细信息 |
| `create_order` | 创建新的订单/报价 |
| `update_order` | 更新现有的订单 |
| `delete_order` | 删除订单 |
| `send_order_email` | 通过电子邮件发送订单 |
### 凭证（5 个工具）
| 工具 | 描述 |
|------|-------------|
| `list_vouchers` | 列出凭证/收据，支持筛选 |
| `get_voucher` | 按 ID 获取凭证详细信息 |
| `create_voucher` | 创建新的凭证 |
| `update_voucher` | 更新现有的凭证 |
| `book_voucher` | 为凭证记录付款 |
### 交易（5 个工具）
| 工具 | 描述 |
|------|-------------|
| `list_check_accounts` | 列出付款账户 |
| `list_transactions` | 列出交易，支持筛选 |
| `get_transaction` | 按 ID 获取交易详细信息 |
| `create_transaction` | 创建新的交易 |
| `update_transaction` | 更新现有的交易 |
### 零件/库存（4 个工具）
| 工具 | 描述 |
|------|-------------|
| `list_parts` | 列出零件/物品，支持筛选 |
| `get_part` | 按 ID 获取零件详细信息 |
| `create_part` | 创建新的零件/物品 |
| `update_part` | 更新现有的零件 |
### 基础（3 个工具）
| 工具 | 描述 |
|------|-------------|
| `get_system_version` | 获取 sevDesk 系统版本 |
| `get_next_sequence_number` | 获取下一个文档编号 |
| `export_data` | 导出特定类型的数据 |
## 通用参数
### 状态代码
**发票/信用额度：**
- `100` - 草稿
- `200` - 已打开/已交付
- `1000` - 已支付
**订单：**
- `100` - 草稿
- `200` - 已交付
- `300` - 已接受
- `500` - 部分已开票
- `750` - 已开票
- `1000` - 已取消
**凭证：**
- `50` - 草稿
- `100` - 未支付
- `1000` - 已支付
### 联系人分类
- `3` - 客户 (Kunde)
- `4` - 供应商 (Lieferant)
- `28` - 合作伙伴
### 订单类型
- `AN` - 报价 (Angebot)
- `AB` - 确认订单 (Auftragsbestätigung)
- `LI` - 交货单 (Lieferschein)
### 国家 ID
- `1` - 德国
- 请参阅 sevDesk 文档获取其他国家
### 单位 ID
- `1` - 件 (Stück)
- `2` - 小时 (Stunde)
- 请参阅 sevDesk 文档获取其他单位
## 示例
### 创建客户
```json
{
"name": "ACME GmbH",
"categoryId": 3,
"defaultTimeToPay": 14,
"vatNumber": "DE123456789"
}
```
### 创建发票
```json
{
"contactId": 12345,
"invoiceDate": "2024-01-15",
"positions": [
{
"name": "咨询",
"quantity": 8,
"price": 150.00,
"taxRate": 19,
"unityId": 2
}
],
"header": "2024 年 1 月发票",
"timeToPay": 14
}
```
### 创建报价
```json
{
"contactId": 12345,
"orderDate": "2024-01-10",
"orderType": "AN",
"positions": [
{
"name": "网页开发",
"quantity": 1,
"price": 5000.00,
"taxRate": 19,
"unityId": 1,
"optional": false
}
]
}
```
## 开发
```bash
# 安装依赖
npm install
# 构建
npm run build
# 在开发环境中运行
npm run dev
```
## 使用 MCP Inspector 测试
```bash
npx @anthropic-ai/mcp-inspector dist/index.js
```
## 许可证
MIT
## 链接
- [sevDesk API 文档](https://api.sevdesk.de/)
- [sevDesk 网站](https://sevdesk.de)
- [GitHub 仓库](https://github.com/Honeyfield-Org/sevdesk-mcp)
