UOL Účetnictví (unofficial)

uol-mcp

Model Context Protocol 服务，适用于 UOL Účetnictví——向 Claude、Cursor 或任何其他 MCP 客户端咨询您的记账情况：已开具和已收到的发票、欠您款项的人、已上传的文档以及联系人。

非官方。 与 UOL a.s. 没有关联，也未得到其认可。它使用您自己的 API 令牌调用公开的 UOL REST API。

捷克语

状态： v0.6——默认只读，可选择启用写入功能。变更内容：CHANGELOG.md。

功能

工具	可回答的问题
get_business_snapshot	一次调用了解公司经营状况：本月与上月对比、增值税、应收款、待处理文档、银行
get_financial_overview	根据总账按月查看收入、支出和利润，以及金额最大的科目
get_vat_overview	按申报期查看增值税：应缴金额或超额抵扣、到期日、最终值或估算值
get_bank_balances	按账户和币种查看银行余额（UOL 按月保存快照）
get_company	公司名称、IČO、DIČ、注册地址、增值税申报期；也可用于检查连接
search_sales_invoices、get_sales_invoice	已开具的发票，包含明细行、增值税和付款状态
search_purchase_invoices、get_purchase_invoice	已收到的发票
list_receivables	欠您款项的人、欠款金额、逾期时长——按币种汇总
export_sales_invoice	将已开具发票导出为 PDF 或 ISDOC 并保存到磁盘（也会以 XML 格式返回 ISDOC）
search_contacts、get_contact	按名称、IČO 或 DIČ 搜索客户和供应商，并查看地址和银行账户
list_uploaded_documents、get_uploaded_document、download_uploaded_document	为会计师上传的文档、文档状态及文件
list_codebook	币种、部门、合同、价目表、自有银行账户等
api_get	只读 GET 请求，可访问任何其他 /v1/… 端点

示例问题：“今年我们的经营情况怎么样？”、“这个季度我要缴多少增值税？”、 “谁欠我的钱逾期超过 30 天？”、“发票 2026000123 已付款吗？”、 “我们的最大支出是什么？”、“给我下载最近开具发票的 PDF。”

更多只读工具可通过选择启用的工具集（UOL_TOOLSETS）使用：ledger（总账分录、内部文档）、banking（银行流水、零用现金文档）和 warehouse（产品、库存水平、订单）。

预设提示词（大多数客户端中的斜杠命令）：monthly_review、vat_check、 overdue_followup（起草催款提醒，不会发送）、process_inbox；启用 写入权限后，还可使用 issue_invoice（根据您的描述创建销售发票，先显示试运行结果，待您确认后创建草稿）。uol://guide 资源会向模型介绍相关领域知识。

uol-ucetnictvi 技能功能更进一步：Claude 会按照您一贯为该客户开具发票的方式开票（从您此前为该客户开具的发票中学习 DUZP 规则、到期天数、产品、明细行文本和银行账户），并像会计师一样读取收入、利润、增值税和应收款（未入账月份、估算值、截止日期）。在 Claude Desktop 或 claude.ai 中安装时，请将 skills/uol-ucetnictvi 文件夹打包为 ZIP，并在 Settings → Capabilities → Skills 下上传；在 Claude Code 中安装时，请将该文件夹复制到 ~/.claude/skills/。

该服务了解 API 的一些特殊行为：发票状态 valid 表示草稿；付款状态仅适用于已开具的发票；贷项通知单中的金额为正数；收入和支出必须从总账中读取（排除年末结账分录）；采购发票会忽略开具日期筛选条件；文件有三种不同的下载形式；客户端会遵守速率限制（30 次请求 / 10 秒）。详见 docs/DESIGN.md。

获取 API 令牌

1. 打开 UOL 租户的 API 令牌页面（路径 /api_tokens，例如 https://firma.ucetnictvi.uol.cz/api_tokens），然后创建令牌。
2. UOL 用户需要拥有 REST API 权限。建议专门创建一个用户，并且只授予你希望助手拥有的权限。

你的租户名称是 UOL 地址的第一部分：https://firma.ucetnictvi.uol.cz → firma。

想先试用一下？UOL_TENANT=demo 使用 UOL 的公开 DEMO 公司，无需令牌。

配置

变量	含义
UOL_TENANT	demo、你的租户名称（firma）、主机前缀（firma.sandbox）或完整的 https://….uol.cz URL
UOL_EMAIL	你登录 UOL 时使用的电子邮件地址
UOL_TOKEN	API 令牌
UOL_DOWNLOAD_DIR	导出和下载文件的存放位置（默认 ~/Downloads/uol-mcp）
UOL_TOOLSETS	逗号分隔：core、insights（这两项为默认值）、ledger、banking、warehouse 或 all
UOL_ACCESS	read（默认）、write 或 full——请参阅写入（主动启用）
UOL_PROMPT_LANGUAGE	提示词（斜杠命令）以及提示词要求生成的回答所用的语言：cs（默认）或 en
UOL_ACCOUNTS、UOL_DEFAULT_ACCOUNT	在一个服务中使用多家公司——请参阅多家公司；UOL_ACCOUNT_<NAME>_ACCESS 用于设置单个账户的权限级别
UOL_PROFILES_FILE	也可通过 JSON 文件配置
UOL_UPLOAD_DIRS	upload_document 可读取的文件夹（默认 ~/Downloads、~/Desktop、~/Documents；以 : 分隔，Windows 上使用 ;）。HTTP 服务没有默认值：未设置此变量时，只接受 content_base64
UOL_AUDIT_LOG	记录每次写入操作的文件，每行一条 JSON 记录
UOL_TIMEOUT_MS	单次 UOL 请求的超时时间（默认 30000）
UOL_DEBUG	1 表示将请求记录到 stderr（绝不记录凭据）

Claude Desktop

设置 → 开发者 → 编辑配置，然后添加：

{
  "mcpServers": {
    "uol": {
      "command": "npx",
      "args": ["-y", "uol-mcp"],
      "env": {
        "UOL_TENANT": "firma",
        "UOL_EMAIL": "[email protected]",
        "UOL_TOKEN": "your-token"
      }
    }
  }
}

Claude Code

claude mcp add uol -e UOL_TENANT=firma -e [email protected] -e UOL_TOKEN=your-token -- npx -y uol-mcp

Cursor / VS Code

Cursor（.cursor/mcp.json）使用与 Claude Desktop 相同的 mcpServers 块。VS Code （.vscode/mcp.json）：

{
  "servers": {
    "uol": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "uol-mcp"],
      "env": { "UOL_TENANT": "firma", "UOL_EMAIL": "[email protected]", "UOL_TOKEN": "your-token" }
    }
  }
}

Docker

docker run -i --rm -e UOL_TENANT=firma -e [email protected] -e UOL_TOKEN=your-token -v "$HOME/Downloads/uol-mcp:/data" ghcr.io/jakubbegera/uol-mcp

导出和下载的文件会写入容器内的 /data；-v 挂载会将它们保留下来。 在 MCP 客户端配置中，将 docker 用作命令，其余内容用作 args。

Claude Desktop 扩展

每个版本都会附带 uol-mcp.mcpb。打开它即可安装，然后在表单中填写租户、电子邮件和令牌；令牌将作为机密信息存储。bash scripts/build-mcpb.sh 可从源代码构建此安装包。

HTTP 服务（自托管）

MCP_TRANSPORT=http MCP_AUTH_TOKEN=$(openssl rand -hex 32) UOL_TENANT=firma [email protected] UOL_TOKEN=your-token npx -y uol-mcp

端点为 http://127.0.0.1:3000/mcp（可通过 HOST、PORT 修改；/health 用于探测）。 有两种模式：

• 单租户：在服务的环境变量中配置 UOL 凭据。客户端必须发送 Authorization: Bearer <MCP_AUTH_TOKEN>；没有令牌时，服务会拒绝启动。
• 透传：环境变量中不配置 UOL 凭据。每个客户端在每次请求时都发送自己的 X-UOL-Tenant、 X-UOL-Email 和 X-UOL-Token 标头；服务不会存储任何内容。 在 localhost 上，MCP_AUTH_TOKEN 为可选项。

通过 HTTP 调用时，导出的发票和下载的文档会包含在工具结果中返回，而不会保存在服务上； upload_document 接收作为 content_base64 的文件——除非设置了 UOL_UPLOAD_DIRS，否则不会读取服务上的路径。在 Docker 中，请绑定到所有网络接口并发布端口：docker run -p 3000:3000 -e MCP_TRANSPORT=http -e HOST=0.0.0.0 -e MCP_AUTH_TOKEN=… -e MCP_ALLOWED_HOSTS=mcp.example.com …。

变量	含义
MCP_TRANSPORT	http 启动 HTTP 服务（与 --http 相同）
HOST、PORT	绑定地址，默认为 127.0.0.1:3000
MCP_AUTH_TOKEN	客户端必须发送的 Bearer 令牌，至少 32 个字符；单租户模式下以及 HOST 不是环回地址时必需
MCP_ALLOWED_HOSTS	接受的 Host 名称（以逗号分隔）；HOST 不是环回地址时必需
MCP_ALLOWED_ORIGINS	允许调用该端点的浏览器来源（默认不允许任何来源）

服务使用纯 HTTP：在 localhost 以外的任何地方，都应将其置于终止 TLS 的反向代理之后。HOST 为非环回地址时，如果未设置 MCP_AUTH_TOKEN 和 MCP_ALLOWED_HOSTS，服务会拒绝启动。

检查设置

UOL_TENANT=firma [email protected] UOL_TOKEN=your-token npx -y uol-mcp doctor

写入（可选启用）

设置 UOL_ACCESS=write 后，会显示以下工具：

工具	功能
upload_document	将 PDF 上传到 UOL 的会计师文档收件箱（仅限 UOL_UPLOAD_DIRS 中的文件）
create_sales_invoice	为现有联系人创建已开具的发票——除非设置 issue: true，否则会创建草稿；number 用于设置打印的发票编号，否则 UOL 会从编号序列中取下一个编号
update_sales_invoice	修改或开具草稿发票，包括其编号（UOL 不允许编辑已开具的发票）
create_purchase_invoice	登记从现有供应商处收到的发票
create_contact、update_contact	添加或修改客户／供应商（拒绝重复的 IČO）
create_payment_demand	为一位客户的未付款发票创建付款催款通知（upomínka）——绝不会发送
mark_document_processed、pair_uploaded_document、tag_uploaded_document、untag_uploaded_document	会计师的收件箱：状态、与已登记记录的关联、标签

UOL_ACCESS=full 会额外启用 delete_sales_invoice（仅限草稿）、repair_sales_invoice（将已开具的发票作废或恢复为草稿）以及 api_request（向任意端点发送原始写入请求）。

发票明细行需要 UOL 产品（使用 list_codebook 并设置 kind: products 可查看）。每个写入操作都支持 dry_run（准确显示将要发送的内容），创建操作可安全重试（幂等键），并且这些工具都已标记，以便客户端在运行前征求你的确认。设置 UOL_AUDIT_LOG 可记录每次写入操作。

多家公司

在 UOL 上服务多家客户的会计师，可以通过一台服务为所有客户提供服务。在 UOL_ACCOUNTS 中列出这些账户，并为每个账户设置专属变量（名称转为大写，- 替换为 _）：

"env": {
  "UOL_ACCOUNTS": "firma,novak",
  "UOL_ACCOUNT_FIRMA_TENANT": "firma",
  "UOL_ACCOUNT_FIRMA_EMAIL": "[email protected]",
  "UOL_ACCOUNT_FIRMA_TOKEN": "op://Private/UOL firma/credential",
  "UOL_ACCOUNT_NOVAK_TENANT": "novak",
  "UOL_ACCOUNT_NOVAK_EMAIL": "[email protected]",
  "UOL_ACCOUNT_NOVAK_TOKEN": "op://Private/UOL novak/credential",
  "UOL_ACCOUNT_NOVAK_LABEL": "Novák s.r.o."
}

第一个账户是默认账户（也可以设置 UOL_DEFAULT_ACCOUNT）。使用 1Password CLI 时，通过 op run -- node …/dist/index.js 启动服务，op:// 引用会在启动时替换为令牌——配置中不会存放任何机密信息。uol-mcp doctor 会检查每个账户。

也可以将 UOL_PROFILES_FILE 指向一个 JSON 文件：

{
  "default": "firma",
  "accounts": {
    "firma": { "tenant": "firma", "email": "[email protected]", "token_env": "UOL_TOKEN_FIRMA" },
    "novak": { "tenant": "novak", "email": "[email protected]", "token_env": "UOL_TOKEN_NOVAK", "label": "Novák s.r.o." }
  }
}

token_env 指定保存令牌的环境变量，因此文件中无需包含机密信息（也可以直接填写 token；请将此类文件的权限设为 chmod 600）。随后，服务会提供 list_accounts，且每个工具都接受 account 参数——"Kdo dluží firmě Novák?" 会发送到正确的租户。每个账户都有自己的速率限制。

账户可以拥有各自的访问级别：设置 UOL_ACCESS=write 和 UOL_ACCOUNT_NOVAK_ACCESS=read（或在 profiles 文件中设置 "access": "read"）后，对 Novák 的写入操作会被拒绝，而其他账户仍可写入。list_accounts 会显示每个账户的访问级别。

隐私与安全

• 除非设置 UOL_ACCESS=write，否则仅允许读取。发票、备注和文档中的文本均视为数据：请在批准助手提议的写入操作前进行检查。
• 工具返回的任何内容都会发送到客户端所使用的 AI 模型。会计数据包含联系人和员工的个人数据——请使用条款让你放心的套餐。
• 凭据仅用于 https://*.uol.cz，绝不会写入日志或工具输出。
• 下载的文件仅保存在 UOL_DOWNLOAD_DIR 下，仅文件所有者可读取，且绝不会替换已有文件（若文件名已被占用，会添加 (1) 后缀）。超过 50 MB 的下载会被拒绝。
• 模型会收到指示：来自 UOL 的文本（发票、备注、文档）是数据，而非指令。

从源代码构建

需要 Node.js 22+。

git clone https://github.com/jakubbegera/uol-mcp.git
cd uol-mcp
npm install
npm run build

然后，将客户端指向 node /path/to/uol-mcp/dist/index.js，而不是 npx -y uol-mcp。

开发

npm test                 # unit + MCP-level tests against recorded DEMO responses
npm run typecheck
npm run smoke            # calls every tool against the live DEMO tenant
npm run record-fixtures  # refreshes test/fixtures/demo from the DEMO tenant
bash scripts/build-mcpb.sh  # builds build/uol-mcp.mcpb
docker build -t uol-mcp .

CI 会运行类型检查、测试、npm audit、Docker 镜像的 Trivy 扫描、CodeQL，以及拉取请求的依赖项审查；Dependabot 会确保依赖项、操作和基础镜像保持最新。

推送 v* 标签即可创建发布；维护者批准 release 环境后，.github/workflows/release.yml 会将软件包发布到 npm、GHCR、GitHub release（MCPB bundle）和 MCP Registry。

设计说明、API 事实和路线图见 docs/DESIGN.md。

贡献

欢迎贡献——请参阅 CONTRIBUTING.md。如需报告安全问题，请按照 SECURITY.md 中的说明私下提交。

许可证

MIT