Infakt MCP Server

inFakt MCP服务器

语言： 英语 | 波尔斯基（波兰语）

用于inFakt API的模型上下文协议（MCP）服务器-一个全面的波兰发票和会计服务。

概述

此MCP服务器提供与inFakt的REST API的无缝集成，使Claude等人工智能助手能够与您的inFakt帐户进行交互：

• 发票管理 -创建、读取、更新和删除增值税发票、更正发票和其他文档类型
• 客户管理 -管理客户数据库
• 产品管理 -维护产品/服务目录
• 成本跟踪 -访问费用文档
• 参考数据 -查询增值税税率、银行账户和其他配置数据

特性

• 发票、客户和产品的完整CRUD操作
• 异步发票创建与状态跟踪
• PDF生成和电子邮件传递
• 高级过滤、分页和排序
• 支持生产环境和沙盒环境
• 全面的错误处理

先决条件

• Node.js 18或更高版本
• inFakt帐户（生产或沙盒）
• inFakt API密钥

安装

1. 克隆此存储库：

git clone 
cd infakt-mcp

1. 安装依赖项：

npm install

1. 构建项目：

npm run build

配置

获取API密钥

生产环境：

1. 登录 事实上
2. 导航到“设置”→ 其他选项→ API
3. 生成具有所需作用域的新API密钥

沙盒环境：

1. 注册地址： 实际 沙箱
2. 导航到“设置”→ API
3. 生成测试API密钥

环境变量

创建一个 .env 文件或设置以下环境变量：

# Required
INFAKT_API_KEY=your_api_key_here

# Optional
INFAKT_USE_SANDBOX=true  # Set to 'true' for sandbox, omit or 'false' for production
INFAKT_BASE_URL=https://api.infakt.pl/api/v3  # Custom base URL (optional)

MCP客户端配置

对于Claude Desktop：

添加到您的 claude_desktop_config.json:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json 视窗: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "infakt": {
      "command": "node",
      "args": ["/absolute/path/to/infakt-mcp/dist/index.js"],
      "env": {
        "INFAKT_API_KEY": "your_api_key_here",
        "INFAKT_USE_SANDBOX": "false"
      }
    }
  }
}

对于其他MCP客户：

根据客户的文档进行配置，确保：

• 命令： node dist/index.js
• 环境变量设置正确
• 工作目录设置为项目根目录

可用工具

发票管理

infakt_create_invoice

异步创建新的增值税发票。

参数：

• client_company_name （必填）：客户公司名称
• payment_method （必填）：现金、转账、卡等。
• services （必填）：一系列服务/产品
• status：草稿（默认）、已支付或打印
• client_id：使用现有客户端
• 新客户端的客户端详细信息（first_name、last_name、tax_code等）
• 其他字段：备注、发票日期、销售日期、付款日期等。

退货： 用于状态检查的任务参考号

infakt_check_invoice_status

检查异步创建的发票的状态。

参数：

• task_reference_number （必填）：来自create_invoice的参考号

infakt_list_invoices

列出所有具有过滤和分页功能的发票。

参数：

• offset：分页偏移
• limit：每页结果（最多100个）
• order：排序顺序（例如，“invoice_date desc”）
• number：按发票号筛选
• client_company_name：按客户端名称筛选
• status：按状态筛选
• invoice_date_from, invoice_date_to：日期范围筛选器
• fields：要返回的逗号分隔字段

infakt_get_invoice

获取特定发票的详细信息。

参数：

• invoice_uuid （必填）：发票UUID
• fields：可选字段选择

infakt_update_invoice

更新现有发票（仅草稿）。

参数：

• invoice_uuid （必填）：发票UUID
• 要更新的字段（客户公司名称、付款方式、服务等）

infakt_delete_invoice

删除发票（仅限草稿）。

参数：

• invoice_uuid （必填）：发票UUID

infakt_download_invoice_pdf

下载PDF格式的发票（base64编码）。

参数：

• invoice_uuid （必填）：发票UUID
• document_type：原件、副本、复印件等。
• locale：pl、en或pe

infakt_send_invoice_email

通过电子邮件发送发票。

参数：

• invoice_uuid （必填）：发票UUID
• recipient_email：自定义收件人（默认使用客户端电子邮件）
• email_subject：自定义主题
• email_message：自定义消息

infakt_mark_invoice_paid

将发票标记为已付款。

参数：

• invoice_uuid （必填）：发票UUID
• paid_date （必填）：付款日期（YYYY-MM-DD）

客户管理

infakt_list_clients

列出所有具有筛选功能的客户端。

infakt_get_client

按ID获取客户详细信息。

infakt_create_client

创建新客户端。

infakt_update_client

更新现有客户端。

infakt_delete_client

删除客户端。

产品管理

infakt_list_products

列出所有经过筛选的产品。

infakt_get_product

按ID获取产品详细信息。

infakt_create_product

创建新产品。

infakt_update_product

更新现有产品。

infakt_delete_product

删除产品。

参考数据

infakt_get_vat_rates

获取可用的增值税税率。

infakt_get_bank_accounts

获取已配置的银行账户。

infakt_get_account_info

获取帐户信息和限制。

成本管理

infakt_list_costs

列出成本文件。

infakt_get_cost

获取成本文档详细信息。

用法示例

示例1：创建发票

Create a new invoice for client "ACME Corp" with:
- Payment method: bank transfer
- One service: "Website Development" for 5000 PLN net with 23% VAT
- Client tax code: 1234567890
- Client address: ul. Główna 1, 00-001 Warsaw, Poland

MCP服务器将：

1. 异步创建发票
2. 返回任务参考号
3. 然后，您可以检查状态并检索发票UUID

示例2：列出最近的发票

List the last 10 invoices from December 2024, sorted by date descending

示例3：通过电子邮件发送发票

Send invoice  via email to client

示例4：生成PDF

Download PDF for invoice  in Polish language

API范围要求

对于要执行的操作，API键必须具有适当的作用域：

• api:invoices:read -阅读发票、客户、产品
• api:invoices:write -创建/更新/删除发票、客户、产品
• api:costs:read -阅读成本文件
• api:costs:write -管理成本
• api:accounting:read -读取会计数据
• api:accounting:write -管理会计操作
• api:sensitive:bank_accounts:write -管理银行账户

速率限制

inFakt API有以下费率限制：

• GET请求：每个IP每60秒300个请求
• 其他方法：每个IP每60秒150个请求
• 发票电子邮件发送：3000/天（付费账户），20/天（免费账户）

发展

以开发模式运行

npm run dev

构建

npm run build

观看模式

npm run watch

测试

使用沙盒环境

集 INFAKT_USE_SANDBOX=true 要使用测试环境：

• 未创建真实发票
• 安全测试集成
• 限额：每月2500张发票

故障排除

身份验证错误（401）

• 验证您的API密钥是否正确
• 检查密钥是否具有所需的作用域
• 确保密钥未过期

需要付款（402）

• 您的计划不支持API访问或已超出文档限制
• 升级您的计划 事实上

速率限制错误（429）

• 请稍候，然后重试
• 实施指数回退
• 考虑缓存响应

验证错误（422）

• 检查是否提供了必填字段
• 验证数据格式（日期为YYYY-MM-DD，有效的增值税税率等）
• 查看响应中的错误消息

资源

• inFakt API文档
• inFakt网站
• 模型上下文协议文档
• MCP规范

许可证

麻省理工学院

支持

有关API问题，请联系inFakt支持，网址： pomoc@infakt.pl

对于MCP服务器问题，请在此存储库中打开问题。