Billy MCP服务器
用于与Billy的会计系统集成的模型上下文协议（MCP）服务器。该服务器提供了与Billy的REST API交互的工具，用于管理发票、联系人、产品、付款和其他会计数据。
特性
- 联系人管理：创建、读取、更新和列出联系人
- 发票管理：创建、读取和列出包含行项目的发票
- 产品管理：创建、阅读和列出带有定价的产品
- 支付处理：创建付款以将发票标记为已付款
- 票据管理：列出并管理供应商账单
- 账户管理：账户访问表
- 组织信息：获取组织详细信息
先决条件
- Node.js 18或更高版本
- 具有API访问权限的Billy帐户
- Billy API访问令牌
安装
- 克隆或下载服务器代码
- 安装依赖项：
npm install- 构建TypeScript代码：
npm run build配置
获取Billy API代币
- 登录您的Billy帐户
- 转到“设置”→ 访问令牌
- 创建新的访问令牌
- 复制令牌以在环境变量中使用
环境变量
设置以下环境变量：
export BILLY_ACCESS_TOKEN="your_billy_access_token_here"MCP客户端配置
将服务器添加到MCP客户端配置中。对于Claude Desktop，请将此添加到您的 claude_desktop_config.json:
{
"mcpServers": {
"billy": {
"command": "node",
"args": ["/path/to/billy-mcp-server/build/index.js"],
"env": {
"BILLY_ACCESS_TOKEN": "your_billy_access_token_here"
}
}
}
}可用工具
组织
billy_get_organization-获取组织详细信息
联系人
billy_list_contacts-列出具有可选筛选功能的联系人billy_get_contact-通过ID获取特定联系人billy_create_contact-创建新联系人billy_update_contact-更新现有联系人
发票
billy_list_invoices-列出具有可选过滤功能的发票billy_get_invoice-按ID获取特定发票billy_create_invoice-使用行项目创建新发票
产品
billy_list_products-列出具有可选过滤功能的产品billy_get_product-按ID获取特定产品billy_create_product-创建具有定价的新产品
支付
billy_list_bank_payments-列出银行付款billy_create_payment-创建付款以将发票标记为已付款
账单
billy_list_bills-列出供应商账单
账户
billy_list_accounts-会计科目表
使用示例
创建联系人
// Using the billy_create_contact tool
{
"name": "Acme Corporation",
"type": "company",
"countryId": "DK",
"street": "Main Street 123",
"city": "Copenhagen",
"zipcode": "1000",
"phone": "+45 12 34 56 78",
"email": "contact@acme.com",
"isCustomer": true,
"paymentTermsDays": 30
}创建发票
// Using the billy_create_invoice tool
{
"contactId": "contact-id-here",
"entryDate": "2024-01-15",
"currencyId": "DKK",
"paymentTermsDays": 30,
"lines": [
{
"productId": "product-id-here",
"description": "Consulting services",
"quantity": 10,
"unitPrice": 1000
}
],
"state": "approved"
}创建付款
// Using the billy_create_payment tool
{
"entryDate": "2024-01-20",
"cashAmount": 10000,
"cashSide": "debit",
"cashAccountId": "bank-account-id",
"associations": [
{
"subjectReference": "invoice:invoice-id-here"
}
]
}API文档
有关Billy的API的详细信息，请访问：https://www.billy.dk/api
发展
以开发模式运行
npm run dev建筑
npm run build文件结构
src/
index.ts # Main server implementation
build/ # Compiled JavaScript output
package.json # Dependencies and scripts
tsconfig.json # TypeScript configuration
README.md # This file错误处理
该服务器包括全面的错误处理功能，用于：
- 无效的API令牌
- 网络连接问题
- 无效的请求参数
- Billy API错误
所有错误都会返回描述性消息，以帮助调试。
支持的Billy API功能
此MCP服务器支持Billy API核心功能，包括：
- ✅ 组织管理
- ✅ 联系人管理（客户/供应商）
- ✅ 发票创建和管理
- ✅ 产品目录管理
- ✅ 支付处理
- ✅ 账单管理（供应商发票）
- ✅ 科目表访问权限
- ✅ 分页和过滤
- ✅ 相关数据包含（侧面加载/嵌入）
- ✅ 错误处理和验证
局限性
- 身份验证仅限于访问令牌（Billy尚不支持OAuth）
- 一些高级功能，如滞纳金、提醒和附件，尚未实现
- 此版本中不包括银行行匹配和日记账交易
安全考虑
- 安全地存储您的Billy访问令牌
- 使用环境变量而不是硬编码令牌
- Billy中的令牌不会过期，但可以从Billy界面撤销
- 每个令牌都与特定的组织相关联
贡献
要扩展此MCP服务器，请执行以下操作：
- 向中添加新工具
ListToolsRequestSchema处理器 - 在中实现相应的API调用
BillyClient类 - 在中添加工具处理逻辑
CallToolRequestSchema处理器 - 用新功能更新此README
添加新工具示例
// 1. Add to tools list
{
name: "billy_new_feature",
description: "Description of the new feature",
inputSchema: {
type: "object",
properties: {
// Define parameters
},
},
}
// 2. Add to BillyClient class
async newFeature(params: any): Promise {
return this.request("GET", "/new-endpoint", params);
}
// 3. Add to request handler
case "billy_new_feature":
const result = await billyClient.newFeature(args);
return { content: [{ type: "text", text: JSON.stringify(result, null, 2) }] };故障排除
常见问题
- “BILLY_CCESS_TOKEN环境变量是必需的”
- 确保您已正确设置环境变量 - 检查您的MCP客户端配置是否包括env部分
- “Billy API错误：401”
- 您的访问令牌无效或已被吊销 - 从Billy的界面生成新令牌
- “Billy API错误：403”
- 您的令牌没有请求操作的权限 - 检查您是否在某些操作中使用公司令牌，而不是用户令牌
- “Billy API错误：404”
- 请求的资源（发票、联系人等）不存在 - 检查您是否使用了正确的ID
- “Billy API错误：422”
- 请求中的数据无效 - 检查必填字段和数据格式（特别是日期：YYYY-MM-DD）
调试模式
要启用更详细的日志记录，您可以修改服务器以记录请求：
// Add to the request method in BillyClient
console.error(`Making ${method} request to ${url}`, data);许可证
MIT许可证-可以根据需要自由修改和分发。
支持
对于Billy API的问题，请联系：dev@billy.dk 对于MCP服务器问题，请在您的存储库中创建问题。