Aikount Mcp

Aikount MCP — 为 Claude、Cursor 和 ChatGPT 提供 AI 驱动的西班牙会计服务

面向西班牙 autónomos 和中小企业的会计 MCP 服务。 将你的会计工作 带到任何 AI Agent 中：开具发票、通过 OCR 录入费用 PDF、核对银行流水并准备 Modelo 303——全部可通过 Claude、Cursor、ChatGPT 或任何 MCP 客户端完成。

Aikount 是一款 Agent 优先的会计 SaaS：一个旨在让 AI 负责会计工作的 Holded 替代方案。此代码仓库是官方的 MCP（Model Context Protocol）服务，通过 Aikount 的公开 REST API 将你的 AI Agent 连接到你的账簿。API 才是产品；Web 界面是为人类用户准备的备用方案。

你是 autónomo 或 gestoría，希望让 AI Agent 负责在西班牙的会计工作吗？ 请从 aikount.com 开始，并将你的 Agent 连接到此 MCP 服务。

可以做什么？（工具）

工具	功能
whoami	验证令牌并返回当前活跃的租户（公司）
list_contacts / create_contact	客户和供应商
list_tax_types	IVA/IGIC/IPSI/IRPF 税种及其用于明细行的 UUID
list_products	产品/服务目录
list_invoices / get_invoice	查询销售发票
create_invoice / issue_invoice	创建草稿并开具发票（分配法定编号）
list_purchases / get_purchase	查询费用/采购发票
ingest_purchase_pdf / get_ingest_job	将 PDF 通过 OCR 录入为费用，不会重复录入
list_treasuries	显示余额的银行 / Stripe / PayPal 账户
list_bank_movements	银行流水，支持筛选
reconciliation_board / reconcile_movement	自动银行对账
list_accounts / ledger / trial_balance	西班牙通用会计科目表（PGC）、分类账及试算平衡表
modelo_303_summary / modelo_303_csv	季度 IVA（Modelo 303）
api_request	访问任何其他 endpoint（参见 OpenAPI）

为什么没有 create_purchase？ 重复的采购发票会导致费用总额、进项 IVA 和银行对账数据出错。 因此，只能通过 ingest_purchase_pdf 添加费用，该工具会按发票身份去重。

安装

你需要 Aikount 的 API key（scope *，前缀为 agl_）。在 Aikount Web 应用中点击 “连接 Agent” 按钮即可生成——页面会显示准确的 export 命令行。

选项 A — Hosted，无需安装（远程 MCP）

使用请求头中的令牌，将客户端连接到 Hosted endpoint：

URL:    https://api.aikount.com/mcp        (streamable-HTTP)
Header: Authorization: Bearer agl_tu_token

支持多租户：每个请求都使用各自的令牌进行身份验证。适用于支持远程 MCP 的客户端。与本地版本提供相同的工具。

选项 B — 本地（此软件包）

export AIKOUNT_TOKEN="agl_xxxxxxxxxxxxxxxxxxxxxxxx"
# opcional, por defecto producción:
# export AIKOUNT_API="https://api.aikount.com/api/v1"

使用 uv 运行（无需安装）：

uvx aikount-mcp@latest

或使用 pip/pipx：

pipx install aikount-mcp   # o: pip install aikount-mcp
aikount-mcp

Claude Desktop / Claude Code

将其添加到 MCP 配置（claude_desktop_config.json，或 Claude Code 中的 .mcp.json）：

{
  "mcpServers": {
    "aikount": {
      "command": "uvx",
      "args": ["aikount-mcp@latest"],
      "env": { "AIKOUNT_TOKEN": "agl_xxxxxxxxxxxxxxxxxxxxxxxx" }
    }
  }
}

Cursor

设置 → MCP → Add new server，使用相同的 command / args / env。

使用场景

• “向 ACME 开具一张 1.200 € 的发票，内容为 5 月份的咨询服务。” Agent 搜索联系人、计算增值税并创建草稿；你确认后即可开具。
• “将这份 Amazon Web Services PDF 录入为支出。” OCR + 在西班牙通用会计科目表中去重并录入支出。
• “我第二季度的增值税情况如何？” 即时汇总 Modelo 303。
• “将银行交易与发票对账。” 自动银行对账（置信度 ≥ 0.95 时自动完成对账）。

约定

• 金额以欧元小数表示（unit_price: 1200.00），而非分；除非 currency 指定其他币种，否则使用 EUR。
• 日期采用 ISO-8601 格式 AAAA-MM-DD。ID 为 UUID。
• 行项目通过 tax_type_id（list_tax_types 返回的 UUID）引用税种，而非文本代码。省略该字段即可继承联系人/产品的税种。
• 错误以 {"error": true, "status_code": ..., "detail": ..., "hint": ...} 的形式返回，便于模型自我纠正（401 时重新认证，422 时修正请求正文）。
• Token 的 scope 为 *——请将其视为密码。公司隔离（多租户）会自动完成。

对于此服务未封装的所有功能，请以 OpenAPI 规范 为准；通过 api_request 访问。

常见问题（FAQ）

什么是 Aikount MCP？

这是一个 MCP（Model Context Protocol）服务，可将 Claude、Cursor 或 ChatGPT 等 AI Agent 连接到你在 Aikount 的账务，让 AI 能够使用西班牙通用会计科目表，开具发票、登记支出、进行银行对账并准备税务申报 （Modelo 303）。

如何将 Claude（或 Cursor/ChatGPT）连接到账务？

使用 uvx aikount-mcp@latest 安装服务，在 Aikount 中通过 “连接 Agent”生成 API key，并将 mcpServers 代码块添加到 MCP 客户端的配置中。几秒钟内，你的 Agent 就能读取和写入账簿。

安全吗？Aikount 会保存我的银行凭据吗？

不会。银行连接通过受监管的 PSD2 网关（Ponto Connect、Salt Edge、GoCardless）建立；Aikount 绝不会存储银行凭据。数据托管在欧盟。API Token 可撤销，并按公司隔离。

适用于西班牙的个体经营者和中小企业吗？

适用。Aikount 专为西班牙个体经营者和中小企业以及为其提供监管服务的会计事务所打造，支持多公司和多币种、西班牙通用会计科目表及 Veri*Factu。它不会取代你的会计师，而是把已完成的工作交给对方审核和签字。

什么是 Modelo 303？AI 能准备申报资料吗？

Modelo 303 是西班牙的季度增值税自我申报表。Agent 会生成按季度汇总的资料（modelo_303_summary）和按交易明细的数据（modelo_303_csv），供审核和提交。

它是 Holded 的替代方案吗？

是。Holded 是按模块划分的套件，而 Aikount 是一款专注于为你处理账务的 AI Agent，价格按开票金额档位计算。对比： aikount.com/alternativas-a-holded。

关于 Aikount

Aikount——面向个体经营者、中小企业和会计事务所的以 Agent 为先的西班牙账务服务。相关资源：

• 🌐 网站：aikount.com
• 🤖 AI 账务：aikount.com/contabilidad-con-ia
• 🏦 自动银行对账：aikount.com/conciliacion-bancaria-automatica
• 🧮 季度增值税计算器（Modelo 303）：aikount.com/calculadora-iva-trimestral
• 🆚 Holded 的替代方案：aikount.com/alternativas-a-holded
• 📚 API 文档：api.aikount.com/docs
• 🧩 Agent 上下文：aikount.com/llms.txt

开发

python -m venv .venv && source .venv/bin/activate
pip install -e ".[dev]"
pytest -q          # 23 tests, sin red (httpx MockTransport)

测试会将每个工具固定到根据实时 OpenAPI 规范验证过的 API 实际路径，确保路径不会悄然失效。

server.json 是此软件包在 MCP 官方注册表中的清单。

许可证

MIT — 参见 LICENSE。