内容
# 工具列表
## Akaunting MCP 服务器
基于 Laravel 的 [模型上下文协议](https://modelcontextprotocol.io) 服务器，用于 [Akaunting](https://akaunting.com)。它将您的 Akaunting 实例暴露为 MCP 工具，以便像 Claude 这样的 AI 客户端可以代表您管理联系人、项目、发票、账单和交易。
> **兼容性：** 构建和调整为 **Akaunting 3.1.21**。工具输入模式镜像该版本的 API 验证规则（必填字段、日期格式、`payment_method` 代码格式等）。此服务器通过其 REST API（`/api`）与 Akaunting 通信。Akaunting 的 API 界面可能会在版本之间发生变化 - 在升级之前，请始终与 [Akaunting 更新日志](https://github.com/akaunting/akaunting/releases) 和 [API 文档](https://akaunting.com/hc/docs/developers/restful-api/) 进行兼容性验证。
>
> **记录付款** 需要 [离线付款](https://akaunting.com/apps/offline-payments) 应用（默认捆绑）。`create_transaction` 默认 `payment_method` 为 `offline-payments.cash.1`，即种子现金方法。
## 工作原理
```
MCP 客户端（例如 Claude Desktop）
│ 授权：基本 <base64(电子邮件:密码)>
│ X-公司-ID：<可选公司 ID>
▼
accounting-mcp.yourdomain.com/mcp
│
├── 验证 Akaunting 密钥中间件
│ 验证您的 Akaunting 实例的凭证
│ （GET /api/ping）。如果失败，返回 401。如果通过，则
│ 相同凭证用于所有后续 API 调用。
│
└── MCP 工具 → Akaunting REST API
```
**身份验证** 完全由 Akaunting 处理。每个用户使用具有 `read-api` 权限的 Akaunting 用户的电子邮件和密码进行身份验证（默认授予管理员角色）。不需要单独的用户数据库。
**多公司：** Akaunting 要求每个请求都有 `company_id`。服务器默认使用 `.env` 中的 `AKAUNTING_COMPANY_ID`，MCP 客户端可以通过发送 `X-Company-ID` 头部来覆盖它。使用 `list_companies` 工具来发现公司 ID。
---
## 要求
- PHP 8.2+
- Composer
- 具有 API 访问权限的 Akaunting 实例（具有 `read-api` 权限的用户）
---
## 安装（Plesk）
### 1. 创建子域名
在 Plesk → **网站和域名** → **添加子域名** 中。
将其命名为 `accounting-mcp`（或您喜欢的任意名称）。
### 2. 克隆仓库
为子域名打开 **SSH 终端** 并运行：
```bash
git clone https://github.com/uk7itsolutions/akaunting-mcp.git .
```
### 3. 安装依赖项
```bash
composer install --no-dev --optimize-autoloader
```
这会从 `.env.example` 创建 `.env` 并自动生成应用程序密钥。如果 `storage/` 和 `bootstrap/cache/` 需要由 Web 服务器写入：
```bash
chmod -R 775 storage bootstrap/cache
```
### 4. 配置 `.env`
打开 `.env` 并设置 Akaunting URL（无尾部斜杠）和默认公司：
```env
AKAUNTING_BASE_URL=https://accounting.yourdomain.com
AKAUNTING_COMPANY_ID=1
```
应用程序通过 `config/akaunting.php` 读取这些内容，并将它们用于每个 API 调用。
### 5. 设置文档根目录
在 Plesk → **网站和域名** → 您的子域名 → **托管设置** 中，
将文档根目录设置为：
```
accounting-mcp.yourdomain.com/public
```
### 6. 启用 nginx 重写（Plesk）
Plesk 在 Apache 前面运行 nginx。默认情况下，nginx 尝试将每个 URL 作为静态文件提供，并在 `/mcp` 等路由上返回 404。为了解决这个问题：
1. Plesk → **网站和域名** → 您的子域名 → **Apache 和 nginx 设置**
2. 在 **其他 nginx 指令** 中，粘贴：
```nginx
location / {
try_files $uri $uri/ /index.php?$query_string;
}
```
3. 点击 **确定**。
### 7. 启用 SSL
在 Plesk → **SSL/TLS 证书** → **Let's Encrypt** → 选中 **将 HTTP 重定向到 HTTPS** → **免费获取**。
### 8. 验证
访问 `https://accounting-mcp.yourdomain.com/` - 您应该会看到一个显示 MCP 端点 URL 的小型 JSON 响应。这确认 Laravel 和 nginx 重写正在工作。
---
## 连接 MCP 客户端
`Authorization` 头部是 HTTP 基本身份验证：base64 编码 `email:password`。例如，`admin@company.com:password` 变为 `YWRtaW5AY29tcGFueS5jb206cGFzc3dvcmQ=`。
将以下内容添加到您的 MCP 客户端配置中（例如 Claude Desktop 的 `claude_desktop_config.json`）：
```json
{
"mcpServers": {
"akaunting": {
"url": "https://accounting-mcp.yourdomain.com/mcp",
"headers": {
"Authorization": "Basic <base64(电子邮件:密码)>",
"X-Company-ID": "1"
}
}
}
}
```
`X-Company-ID` 是可选的；省略它以使用默认的 `AKAUNTING_COMPANY_ID`。
---
## 可用工具
| 工具 | 描述 |
|---|---|
| `list_contacts` | 列出联系人，按类型（客户/供应商）或搜索筛选 |
| `get_contact` | 获取单个联系人的完整详细信息 |
| `create_contact` | 创建客户或供应商 |
| `update_contact` | 更新现有联系人的字段 |
| `list_items` | 列出项目（产品和服务） |
| `create_item` | 创建具有销售/购买价格的项目 |
| `list_documents` | 列出发票和账单，按类型或搜索筛选 |
| `get_document` | 获取单个文档的完整详细信息，包括行项目 |
| `create_document` | 从行项目创建发票或账单 |
| `update_document` | 更新发票或账单（加载当前值，覆盖更改） |
| `cancel_document` | 解释不支持通过 API 取消，并建议使用 Web UI 取消按钮或 `delete_document` |
| `delete_document` | 按 ID 删除发票或账单 |
| `list_transactions` | 列出收入和支出付款 |
| `create_transaction` | 记录收入或支出付款 |
| `list_accounts` | 列出财务账户（银行，现金等） |
| `list_categories` | 列出类别，按类型筛选 |
| `list_taxes` | 列出税率 |
| `list_currencies` | 列出已配置的货币 |
| `list_companies` | 列出用户可以访问的公司（查找公司 ID） |
---
## 项目结构
```
app/
├── Http/
│ └── Middleware/
│ └── ValidateAkauntingKey.php # 验证 Basic 凭证对抗 /api/ping
├── Mcp/
│ ├── Servers/
│ │ └── AkauntingServer.php # 注册所有工具
│ └── Tools/ # 每个 MCP 工具一个类（共 16 个）
└── Services/
└── AkauntingClient.php # Akaunting REST API 的 HTTP 客户端
routes/
├── ai.php # 在 /mcp 注册 MCP 服务器
└── web.php # / 健康检查 JSON
bootstrap/app.php # 中间件别名 + /mcp 的 CSRF 排除
config/akaunting.php # 从 .env 读取 AKAUNTING_BASE_URL 和 AKAUNTING_COMPANY_ID
```
---
## 许可证
该项目根据 [MIT 许可证](LICENSE) 授权。
它仅通过 REST API 与 Akaunting 通信，不包含任何 Akaunting 源代码。
