@frihet/mcp Server

面向业务管理的 AI 原生 MCP 服务。
Servidor MCP nativo con IA para gestión empresarial.

_{适用于 Claude · ChatGPT · Cursor · Windsurf · Cline · Antigravity · Codex · Copilot · Gemini CLI，以及任何兼容 MCP 的客户端。}

---

分发

渠道	状态	安装方式
npm	已上线	npx @frihet/mcp-server
远程端点	已上线	https://mcp.frihet.io/mcp（无需安装，使用 OAuth 或 API 密钥）
Smithery	已上线	smithery.ai/servers/frihet/frihet-mcp
MCP Registry	已上线	registry.modelcontextprotocol.io
GitHub MCP Registry	已上线	github.com/mcp/io.frihet/erp
Glama	已上线	glama.ai/mcp/servers/Frihet-io/frihet-mcp
mcp.so	自动索引（未经验证）	mcp.so — 从 npm 和 GitHub 索引
PulseMCP	自动索引（未经验证）	pulsemcp.com — 从 npm 和 GitHub 索引
Cursor Marketplace	即将推出	cursor.com/marketplace
ChatGPT Apps	即将推出	chatgpt.com
Anthropic Claude Directory	即将推出	claude.ai/settings/connectors

**实际情况：**目录包含 156 个规范操作。本地完整配置提供 161 个工具名称、11 个资源和 10 个提示词（156 个规范操作加上 5 个财务别名）。托管分组配置提供 164 个工具名称、7 个资源和 10 个提示词（相同名称加上 3 个发现工具；由 API 支持的资源仅在本地提供）。单独审核的 OpenAI 配置提供 33 个工具名称、0 个资源和 0 个提示词。目录收录不代表每个工作区都启用了相应的后端 API。

---

这是什么

一个 MCP 服务，可将 AI 助手连接到 Frihet。通过对话创建发票。用自然语言查询支出。在 IDE 中管理整个业务。

You:     "Create an invoice for TechStart SL, 40 hours of consulting at 75 EUR/hour, due March 1st"
Claude:  Done. Invoice INV-2026-089 created. Total: 3,000.00 EUR + 21% IVA = 3,630.00 EUR.

156 个规范操作。5 个财务别名。10 个提示词。本地软件包提供 11 个资源；托管 Worker 特意只提供 7 个静态资源，由 API 支持的工作区资源仅在本地配置中提供。

---

立即试用（无需注册）

无需任何设置即可体验 — 无需账户或 API 密钥：

FRIHET_DEMO=1 npx -y @frihet/mcp-server

在演示模式下，服务会使用逼真的示例数据作答（包含 IVA/IGIC 的西班牙发票、支出、客户、产品、银行账户等）——每条记录都使用 demo_ 前缀 ID，服务启动时会显示 DEMO MODE 横幅。不会保存任何数据，也不会发起任何网络调用。写入操作会进行模拟，财务操作（电子发票、VeriFactu、TicketBAI、FACe、薪资）会返回明确标注的模拟结果 — 绝不会真正提交给任何税务机关。

准备好处理真实数据后，移除该标志并添加密钥（app.frihet.io → 设置 → API 密钥）。请参阅下文的安装。

---

面向 AI Agent

如果你是 Agent，而不是在阅读页面的人，那么你需要的信息都以机器可读形式提供，并由运行中的服务生成——无需解析此 README。

内容	位置
接入规范：各客户端的快速入门、身份验证、安全工作流、需由人类决定的工具列表、错误恢复	docs/agent-onboarding.json — 也随 npm 包一同发布
各工具的能力事实：callability、writesFrihet、externalInteraction、externalSideEffects	tools/list 中每个条目的 _meta["io.frihet/capability"]
连接后如何操作	initialize 返回的 instructions 字符串 — 客户端会自动提供给你

该规范概括了以下三条规则：

1. 先了解情况，再采取行动。 get_business_context 和 frihet://tax/rates 资源决定正确的税务处理方式。不要凭记忆回想西班牙税率。
2. 起草、展示、停止。 create_invoice、create_quote 和 create_credit_note 默认均为 status=draft — 没有税务编号、没有哈希，也不会发送给税务机关。展示草稿，然后交还给用户。
3. 不要擅自代行人类决策。 任何 externalSideEffects 非空的工具都会触达客户的收件箱、Webhook、资金或 AEAT / VeriFactu / TicketBAI / FACe。其中有些工具还要求 confirm=true；该标志用于记录人类的决定 — 切勿为了执行自己的计划而设置它。

docs/agent-onboarding.json 由运行中的接口通过 npm run generate:agent-onboarding 重新生成，并由 CI 通过 npm run gate:agent-onboarding 进行检查，因此其中的工具列表和数量不会与服务不一致。

---

安装

本地 npm/stdio 安装需要 Node 22.23.4+ (22.x)、24.22.1+ (24.x) 或 26.12.1+ (26.x)，以涵盖2026 年 10 月的 Node 安全修复。Node 20 已停止支持：启动服务前，请升级 MCP 客户端使用的 Node 运行时。CI 使用 Node 22.23.4。

此源码变更不会更新先前发布的 npm 包元数据或用户已安装的 Node 运行时。更新包元数据需要另行发布 npm 版本；用户现在即可升级运行时。远程 Cloudflare Worker 使用独立的运行时和发布流程。

一行命令（Claude Code、Cursor、Copilot、Codex、Windsurf、Gemini CLI 等）

npx skills add Frihet-io/frihet-mcp

Claude Code 插件（技能 + MCP 服务，一次安装）

此仓库也是一个 Claude Code 插件（frihet-erp）：安装后会同时配置业务管理技能和 MCP 服务。

# Try it locally
claude --plugin-dir /path/to/frihet-mcp

Marketplace 上架尚待完成。今天即可使用上方的本地插件命令，或下方的 Claude Code MCP 命令进行连接。

调用技能：/frihet-erp:frihet-mcp。捆绑的 .mcp.json 会通过 npx 启动 @frihet/mcp-server — 请在环境中设置 FRIHET_API_KEY（前往 app.frihet.io → Settings → API keys 获取）。

便携式 Claude 插件预览版捆绑了真实的应收账款、文档起草和月度审查技能，并使用现有的公开远程 MCP。在 Claude Code 中加载 plugins/claude/frihet-erp，或在聊天/Cowork 中上传该文件夹的 ZIP 文件。其技能会指导操作方式；不会筛选托管目录，也不会获得 Directory 审批。上方根目录中的本地 MCP 设置仍使用现有的 API 密钥配置。

Claude Code — 一条命令

claude mcp add frihet -s user -e FRIHET_API_KEY=fri_your_key_here -- npx -y @frihet/mcp-server
claude mcp list          # verify: frihet ✓ Connected

CLI 会负责管理配置文件，因此无需手动编辑，也不会弄错路径。（用户范围会写入 ~/.claude.json，而不是 ~/.claude/mcp.json。）

Codex CLI — 一条命令

codex mcp add frihet --env FRIHET_API_KEY=fri_your_key_here -- npx -y @frihet/mcp-server
codex mcp list           # verify

Codex 配置使用 TOML，而非 JSON。codex mcp add 会写入：

[mcp_servers.frihet]
command = "npx"
args = ["-y", "@frihet/mcp-server"]

[mcp_servers.frihet.env]
FRIHET_API_KEY = "fri_your_key_here"

将 JSON mcpServers 代码块粘贴到 ~/.codex/config.toml 会导致 TOML 解析错误，使 整个 Codex 配置失效，而不只是此服务。请使用上方的命令。

Claude Desktop、Cursor、Windsurf、Cline — JSON 配置

{
  "mcpServers": {
    "frihet": {
      "command": "npx",
      "args": ["-y", "@frihet/mcp-server"],
      "env": {
        "FRIHET_API_KEY": "fri_your_key_here"
      }
    }
  }
}

工具	配置文件
Claude Desktop	~/Library/Application Support/Claude/claude_desktop_config.json
Cursor	.cursor/mcp.json or ~/.cursor/mcp.json
Windsurf	~/.windsurf/mcp.json
Cline	VS Code 设置或 .cline/mcp.json

以上 JSON 配置适用于这四个客户端，只有文件路径不同。Claude Code 和 Codex 不在此表中——它们通过上文所示的 CLI 命令管理自己的配置。

远程（无需安装）

使用托管端点 mcp.frihet.io——无需本地依赖，运行于 Cloudflare Workers。

使用 API 密钥：

{
  "mcpServers": {
    "frihet": {
      "type": "streamable-http",
      "url": "https://mcp.frihet.io/mcp",
      "headers": {
        "Authorization": "Bearer fri_your_key_here"
      }
    }
  }
}

使用 OAuth 2.0 + PKCE（基于浏览器的登录，无需 API 密钥）：

支持 OAuth 的客户端（Claude Desktop、Smithery 等）可直接连接到 https://mcp.frihet.io/mcp，并通过浏览器进行身份验证。该服务实现了完整的 OAuth 2.1 授权码流程，并使用 PKCE。

获取 API 密钥

1. 登录 app.frihet.io
2. 前往 设置 > API
3. 点击 创建 API 密钥
4. 复制密钥（以 fri_ 开头）——该密钥仅显示一次

---

你可以做什么

与 ERP 对话。以下是真实的提示词，不是营销文案。

发票

"Show me all unpaid invoices"
"Create an invoice for Acme SL with 10h of consulting at 95/hour"
"Mark invoice abc123 as paid"
"How much has ClientName been invoiced this year?"

费用

"Log a 59.99 EUR expense for Adobe Creative Cloud, category: software, tax-deductible"
"List all expenses from January"
"What did I spend on travel last quarter?"

客户

"Add a new client: TechStart SL, NIF B12345678, email [email protected]"
"Show me all my clients"
"Update ClientName's address to Calle Mayor 1, Madrid 28001"

CRM

"Add a contact to Acme SL: Ana Garcia, CTO, [email protected]"
"Log a call with TechStart: discussed Q2 proposal, they're interested in upgrade"
"Add a note to ClientName: prefers invoices in English, payment NET 30"
"Show me all activities for Acme SL"

报价单

"Create a quote for Design Studio: logo design (2000 EUR) + brand guidelines (3500 EUR)"
"Show me all pending quotes"

Webhook

"Set up a webhook to notify https://my-app.com/hook when invoices are paid"
"List all my active webhooks"

---

预期效果

此 MCP 是一个结构化数据接口——你用自然语言描述需求，AI 就会在 Frihet 中创建、查询或修改业务记录。156 个规范操作中的大多数都是通过 REST API 执行的 CRUD 操作，其余则是只读摘要和财税／电子发票操作。别名和发现名称会单独计数。

非常适合：

"Create an invoice for TechStart SL, 40h consulting at 75 EUR/h"   --> creates the invoice
"Show unpaid invoices over 1,000 EUR"                               --> queries and filters
"Log a 120 EUR expense for the Madrid train, category: travel"      --> records the expense
"Update client Acme's email to [email protected]"                     --> modifies the record

不支持：

• OCR 或 PDF 扫描——无法上传发票图片并让它读取
• 文件上传或附件处理
• 任何形式的图像处理

如果你需要将纸质发票或收据数字化，请先提取其中的数据（例如使用 Claude Vision API、专用 OCR 服务或手动录入），然后使用 MCP 创建记录：

1. Scan/photograph the invoice
2. Use Claude Vision: "Read this invoice image and extract the vendor, items, amounts, and dates"
3. Then: "Create an expense in Frihet for [extracted data]"

---

目录操作（156）

发票（12）

工具	功能
list_invoices	分页列出发票
get_invoice	按 ID 获取发票完整详情
create_invoice	创建包含明细项的新发票
update_invoice	更新发票的任意字段
delete_invoice	删除草稿发票；已发送／已付款的发票会被取消而非销毁（需要 confirm=true）
search_invoices	按客户名称、日期或状态查找发票
send_invoice	通过电子邮件向客户发送发票（PDF 附件）——会联系第三方，需要 confirm=true
mark_invoice_paid	将发票标记为已付款，可选填付款日期
get_invoice_pdf	获取有大小限制的发票 PDF 字节数据（Base64 格式）
get_invoice_einvoice	获取发票的有大小限制的 XML 或 Factur-X PDF 字节数据
create_credit_note	创建关联到现有发票的贷项通知单
apply_late_fee	对逾期发票收取滞纳金

费用（5）

工具	功能
list_expenses	分页列出费用
get_expense	获取费用详情
create_expense	记录一笔新费用
update_expense	修改费用
delete_expense	删除费用

客户（5）

工具	功能
list_clients	列出所有客户
get_client	获取客户详情
create_client	注册新客户
update_client	更新客户信息
delete_client	移除客户

CRM：联系人（3）

工具	功能
list_client_contacts	列出客户的所有联系人
create_client_contact	为客户添加联系人
delete_client_contact	从客户中移除联系人

CRM：活动（2）

工具	功能
list_client_activities	列出 CRM 活动（电话、电子邮件、会议、任务）
log_client_activity	记录与客户相关的电话、电子邮件、会议或任务

CRM：备注（3）

工具	功能
list_client_notes	列出客户的所有备注
create_client_note	为客户添加自由格式的备注
delete_client_note	删除客户的备注

产品（5）

工具	功能
list_products	列出产品和服务
get_product	获取产品详情
create_product	添加产品或服务
update_product	更新价格或详情
delete_product	删除产品

报价（6）

工具	功能
list_quotes	列出所有报价
get_quote	获取报价详情
create_quote	起草新报价
update_quote	修改报价
delete_quote	仅删除没有发送、回复、附件或转换证据的干净草稿；拒绝删除受保护的草稿；取消非草稿（需要 confirm=true）
send_quote	通过电子邮件向客户发送报价以供确认

Webhook（6）

工具	功能
list_webhooks	列出已配置的 webhook
get_webhook	获取 webhook 详情
create_webhook	注册新的 webhook 端点
update_webhook	修改事件或 URL
delete_webhook	移除 webhook
test_webhook	向已配置的 webhook 端点发送测试负载

智能分析（4）

工具	功能
get_business_context	完整快照：个人资料、方案、近期活动、主要客户、当前月份
get_monthly_summary	月度损益：收入、支出、利润、纳税义务、按收入排序的主要客户
get_quarterly_taxes	季度税务准备：Modelo 303/130 字段、已收税款与可抵扣税款、纳税义务
duplicate_invoice	克隆发票以用于定期结算（复制项目、客户和税项，初始状态为草稿）

电子发票（10）

工具	功能
send_einvoice	通过电子邮件 / Chorus Pro / SDI / PEPPOL / 下载，以 11 种格式（XRechnung、Factur-X、FatturaPA、PEPPOL、Facturae、UBL、CII）发送发票
get_einvoice_status	轮询 Hatchet 工作流运行状态，直至成功/失败 — 返回 ackId、XML URL、PDF/A-3 URL
validate_einvoice_xml	根据格式架构和 schematron 规则（KOSIT / Mustang / XSD / Schematron）验证原始 XML
export_datev	以 CP1252 编码将会计数据导出为 DATEV EXTF（Buchungsstapel / Debitoren / Kreditoren）
einvoice_export	以机器可读格式（JSON/XML）导出电子发票数据，以供存档或集成
face_submit	将发票提交至 FACe（西班牙 B2G 政府电子发票平台）
face_status	轮询已提交发票在 FACe 的提交状态
ticketbai_submit	向巴斯克地区税务机关（Hacienda）提交 TicketBAI 财税记录
ticketbai_status	轮询巴斯克地区税务机关的 TicketBAI 提交状态
ksef_submit	NOT_DEPLOYED — 将发票提交至 KSeF（波兰）— 存根：Frihet-ERP 中的传输功能已准备就绪，但尚未作为实时端点开放（生产环境需等待 KSeF 证书）；激活前将返回标记为“不可用”的错误

时间跟踪（6）

工具	功能
list_time_entries	列出时间条目，可按用户、项目、日期范围和可计费状态筛选
get_time_entry	按 ID 获取单个时间条目的完整详情
create_time_entry	为项目记录工时（可计费标志、描述、日期）
update_time_entry	更新现有时间条目的任意字段（PATCH 语义）
delete_time_entry	软删除时间条目（需要 confirm=true）
get_time_summary	汇总某个时间段的总工时、可计费工时和不可计费工时，可选按用户/项目/日期分组（groupBy）

Recurring Invoices（8）

工具	功能说明
list_recurring_invoices	列出所有定期发票模板（按启用／暂停状态筛选）
get_recurring_invoice	按 ID 获取定期模板的完整详情
create_recurring_invoice	创建新的定期发票模板（每日／每周／每月／每季度／每年）
update_recurring_invoice	更新模板字段——仅影响未来生成的发票
pause_recurring_invoice	暂停启用的模板——暂停期间不会生成发票
resume_recurring_invoice	恢复已暂停的模板——下一张发票将在下一个预定周期生成
delete_recurring_invoice	永久删除模板（必须设置 confirm=true）
run_recurring_now	显式设置 confirm=true，以完整和分组模式生成下一张定期发票；工作区设置可能会触发财税开具、提交和 Webhook

Team Management（4）

工具	功能说明
list_team_members	列出启用的成员和待处理的邀请（不包括所有者）
invite_team_member	通过电子邮件邀请新成员并指定角色（admin/editor/accountant/viewer）
update_team_member_role	更改现有成员的角色（admin/editor/accountant/viewer）
remove_team_member	从工作区移除成员（必须设置 confirm=true）

Gestoria — Accountants（5）

工具	功能说明
gestoria_message_send	在上下文主题中发送消息（documentRequest / filingItem / obligation）
gestoria_messages_list	列出主题中的消息，按时间从新到旧排列；使用 before 向前翻页
gestoria_template_create	创建可重复使用的文件请求模板，包含变量和到期日期偏移量
gestoria_template_bulk_send	一次调用即可向最多 500 个客户工作区批量发送模板
gestoria_aging_consolidated	跨客户应收账款账龄报告（账龄区间、按工作区细分、逾期金额排名）

Audit GL（3）

工具	功能说明
frihet_gl_entry_approve	批准总账分录（仅限 gestor/admin——信任区域）
frihet_gl_entry_reject	拒绝总账分录并填写必需的原因（信任区域）
frihet_gl_entry_audit_log	获取总账分录的完整审计记录

White-label Portal Domain（3）

工具	功能说明
frihet_portal_domain_add	向客户门户添加自定义域名（返回 DNS CNAME 记录）
frihet_portal_domain_verify	验证自定义门户域名的 DNS 传播情况
frihet_portal_domain_remove	移除自定义门户域名（恢复为默认的 Frihet 子域名）

Self-onboard & VIES（2）

工具	功能说明
frihet_portal_onboard_link_generate	为潜在客户生成有时限的自助入驻链接
frihet_tax_id_vies_lookup	通过 VIES 验证欧盟 VAT 号码（CIF intracomunitario）

IGIC — Canary Islands Indirect Tax（4）

工具	功能说明
frihet_modelo_415_summary	M415 年度业务交易额 >€3,005（加那利群岛版 M347）——尚未部署，返回 NOT_DEPLOYED
frihet_modelo_425_summary	加那利群岛企业年度 IGIC 汇总表 M425——尚未部署，返回 NOT_DEPLOYED
frihet_modelo_418_summary	特别集团实体制度下的月度个体 IGIC 申报表 M418——尚未部署，返回 NOT_DEPLOYED
frihet_aiem_calculate	加那利群岛 AIEM（进口税）计算——尚未部署，返回 NOT_DEPLOYED

Impuesto sobre Sociedades — Corporate Tax（2）

工具	功能说明
frihet_modelo_200_summary	Modelo 200 年度 IS 申报表——尚未部署，返回 NOT_DEPLOYED
frihet_modelo_202_summary	Modelo 202 分期付款（1P/2P/3P）——尚未部署，返回 NOT_DEPLOYED

银行分类规则（2）

工具	功能
frihet_bank_rules_list	列出所有银行自动分类规则（条件、操作和状态）
frihet_bank_rule_create	创建新规则，根据描述、金额和交易对手自动分类交易

存款（7）

工具	功能
list_deposits	分页列出存款
get_deposit	按 ID 获取存款详情
create_deposit	记录新的客户存款
update_deposit	更新存款字段
delete_deposit	删除存款（必须设置 confirm=true）
apply_deposit	将存款余额抵扣发票
refund_deposit	在 Frihet 记账中记录存款退款，必须设置 confirm=true；可选的 amount 用于记录指定金额，不填写则记录剩余可退款余额。不会转账

供应商（5）

工具	功能
list_vendors	列出所有供应商
get_vendor	获取供应商详情
create_vendor	添加新供应商
update_vendor	更新供应商信息
delete_vendor	删除供应商

银行业务（5）

工具	功能
list_bank_accounts	列出已连接的银行账户
get_bank_account	获取银行账户详情
list_transactions	使用筛选条件列出银行交易
categorize_transaction	为交易指定类别以及支出或收入类型
match_transaction_to_invoice	将银行交易关联到现有发票

税务 — 西班牙税务申报表（7）

工具	功能
get_modelo_303_summary	季度 IVA 申报表（Modelo 303）——已收取与可抵扣金额、应付净额
get_modelo_130_summary	个体经营者季度 IRPF 分期预缴税（Modelo 130）
get_modelo_390_summary	年度 IVA 汇总（Modelo 390）
get_modelo_180_summary	租赁年度预扣税汇总（Modelo 180）——尚未部署，返回 NOT_DEPLOYED
get_modelo_347_summary	年度第三方交易汇总（金额超过 3,005 欧元，Modelo 347）
verifactu_status	获取税务记录的 VeriFactu 提交状态
verifactu_resubmit	重新提交被拒绝的 VeriFactu 税务记录
ticketbai_status	查询 TicketBAI 提交状态——交叉引用自电子发票（10）；不计入本节的 7 项

度假租赁 / 住宿（5）

工具	功能
list_reservations	使用筛选条件列出租赁预订
get_reservation	获取预订详情
create_reservation	创建新预订
list_properties	列出所有租赁房源
sync_channel	触发 OTA 渠道同步（Airbnb、Booking.com 等）

POS — 销售终端（4）

工具	功能
list_terminals	列出已注册的 POS 终端
get_sale	获取 POS 销售交易详情
list_sales	分页列出 POS 销售记录
refund_sale	为 POS 销售开具退款

厨房 / 餐厅（6）

工具	功能
list_kitchen_tickets	列出实时看板中的厨房订单票据，可按状态或工作站筛选
get_kitchen_ticket	按 ID 获取单张厨房票据，包含所有菜品及其各自状态
update_kitchen_ticket	推进票据状态（已排队 → 准备中 → 已备好 → 已上菜），或将其重新分配到其他工作站
list_kitchen_stations	列出所有厨房工作站，包含 ID、名称和启用状态
list_menu_items	列出厨房菜单目录，支持全文搜索以及启用/停用筛选
kitchen_flow_summary	检测进度缓慢的工作站：按工作站汇总未完成票据，并标记瓶颈

人力资源（9）

工具	功能
leave_request_create	创建请假申请（休假、病假、事假）
leave_approve	批准待处理的请假申请
leave_reject	拒绝请假申请并说明原因
leave_cancel	取消已批准或待处理的请假申请
leave_list	按筛选条件列出请假申请（用户、状态、日期范围）
attendance_clock_in	记录员工上班打卡
attendance_clock_out	记录员工下班打卡
overtime_report	读取所选 YYYY 或 YYYY-MM 记录中的每日／每周加班情况、汇总分钟数／小时数及计算得出的合规提醒
anomaly_list	列出考勤异常（漏打卡、加班过多）

薪资（2）

工具	功能
payroll_export	读取已规范化、可用于薪资处理的员工数据；format 值是回显的目标标签，并非生成的文件
payroll_checklist	列出可支付员工及其薪资档案准备情况、缺失字段和月度审核状态

入职 — 经由 #124 撤回

由于截至此版本，Frihet-ERP 的 /v1/onboarding/* 接口系列并不存在，因此已撤回 onboarding_status 和 onboarding_persona_set 工具。审计记录和先例请参阅 问题 #124（src/tools/igic.ts 展示了用于后端 API 尚未发布的接口系列的内联 NOT_DEPLOYED 存根模式；入职工具选择了完全撤回，因为目录不应对没有实际处理程序的工具作出过度承诺）。

如果未来的 Frihet-ERP 版本发布了该接口系列，请恢复 src/tools/onboarding.ts、src/tools/shared.ts 中的 onboardingStatusOutput / onboardingPersonaResultOutput 模式、IFrihetClient 上的 getOnboardingStatus / setOnboardingPersona 方法，以及 src/tools/register-all.ts 中的注册（src/__tests__/d4b-hr-payroll-onboarding-tools.test.ts 中的 Onboarding tools — withdrawn via #124 测试会在此处失败，并提醒后续维护者这里原本包含的内容）。

权限（2）

工具	功能
permissions_matrix	获取文档所述 RBAC 模型快照（不保证运行时授权）
permissions_me	对比 RBAC 模型字段与实际 API 密钥作用域及已知的作用域拒绝情况（并非详尽无遗）

期间结账（3）

工具	功能
period_close_status	获取当前或所选 YYYY 财年的范围、开放／关闭状态及可为空的结账详情
period_close	关闭会计期间（仅限 gestor／管理员 — TRUST AREA）
period_reopen	重新开启已关闭期间，且必须说明原因（TRUST AREA）

所有规范操作（及其别名）均通过 outputSchema 返回结构化输出——类型化 JSON，而非原始文本。列表响应的结构遵循其 API 系列；并非所有列表端点都支持分页。

能力与副作用真实性

在完整 MCP 接口中，每个 tools/list 条目都包含 _meta["io.frihet/capability"]：

• registered 表示此服务版本中存在该名称和处理程序；
• callability 为 api_dependent（处理程序会调用 API；部署、工作区启用状态和授权仍会决定是否可调用）、runtime_checked（处理程序会明确区分后端缺失与数据为空）、deferred、unavailable 或 local——绝不会无条件声称“可用”；
• writesFrihet、externalInteraction 和 externalSideEffects 用于区分状态变更以及对外部实体／提供方的调用；
• MCP 操作注解仍是只读、破坏性、幂等和开放世界提示的标准来源。

ChatGPT/OpenAI 宿主是经过单独审核的接口：恰好包含 33 个业务操作，描述完整；不包含发现类元工具、提示词或资源。其 17 个读取操作和 16 个写入操作范围刻意收窄，所有写入操作都要求字面值 confirm=true。其中 10 个写入操作可能会向工作区所有者先前配置的活跃端点发送完整业务事件；Webhook 管理本身仍不包含在内。此外，此接口还排除了直接发送电子邮件、旧版月度摘要、原始发票 PDF、发票生命周期转换、更新现有报价、受监管申报、删除客户父记录、删除及其关联文件的费用、删除产品以及删除供应商。不得根据完整目录推断此接口的能力。

---

资源

AI 可读取的上下文，帮助其做出更明智的决策。

本地包提供 11 个资源：7 个静态参考资源，加上 4 个由 API 提供数据的工作区资源。托管 Worker 提供 7 个静态资源。经 OpenAI 审核的宿主不提供任何资源。

静态（参考数据，不调用 API）：

资源	URI	提供内容
API 架构	frihet://api/schema	OpenAPI 摘要：端点、身份验证、速率限制、分页、错误代码
税率	frihet://tax/rates	按西班牙财政区划分的税率：IVA、IGIC、IPSI、欧盟反向征收、IRPF
税务日历	frihet://tax/calendar	所列西班牙税务表格的季度和年度申报截止日期
费用类别	frihet://config/expense-categories	8 个类别及其抵扣规则、IVA 处理方式和摊销信息
发票状态	frihet://config/invoice-statuses	状态流转（草稿 > 已发送 > 已付款／逾期 > 已取消）、转换规则、Webhook 事件
货币	frihet://config/currencies	40 种受支持的货币及其 ISO 代码、符号、小数位数和区域格式
国家／地区	frihet://config/countries	61 个受支持的国家／地区及其财政区、默认税率、货币和发票前缀

动态（来自你账户的实时数据）：

资源	URI	提供内容
企业资料	frihet://business-profile	你的企业信息、套餐、默认设置、近期活动和主要客户
月度快照	frihet://monthly-snapshot	本月损益、收入、费用、纳税义务
逾期发票	frihet://overdue-invoices	所有已过到期日的发票（最多 100 张）
套餐限制	frihet://status/plan-limits	实时套餐级别、使用量计数器、每月发票数量、API 速率限制

---

提示词（10）

预构建工作流，AI 可按引导执行多步操作。

提示词	功能	参数
monthly-close	结清本月：检查未付款的发票、归类支出、核查纳税义务并生成摘要	month?（YYYY-MM）
onboard-client	为新客户设置正确的所在地税率，可选择创建欢迎报价单	clientName、country?、region?
quarterly-tax-prep	准备季度纳税申报：计算 IVA/IGIC、识别可抵扣项目、预览 Modelo 303/130/420	quarter?、fiscalZone?
overdue-followup	查找逾期发票、起草跟进消息并建议付款提醒	--
new-client-invoice	在一个工作流中创建客户和首张发票，并查询税率	clientName、country?
expense-report	按类别汇总并生成支出报告，列出可抵扣总额	month?（YYYY-MM）
year-end-close	完整的年度结账：季度审查、待处理发票、未归类支出和年终清单	year（YYYY）
cash-flow-forecast	预测未来几个月的现金流：定期收入、支出、逾期应收款和纳税截止日期	months?（默认：3）
invoice-aging-review	应收账款账龄分析：按账龄区间（0-30/31-60/61-90/90+ 天）归类未付款发票、列出主要欠款人并提供催收措施	--
expense-batch	批量处理支出：归类、应用税率并标记缺失的收据	fiscalZone?

---

工作原理

graph LR
    AI["Your AI assistant"]
    MCP["frihet-mcp"]
    API["api.frihet.io"]
    DB["Frihet ERP"]

    AI -- "create_invoice()" --> MCP
    MCP -- "POST /v1/invoices" --> API
    API --> DB
    DB -- "201 + invoice data" --> API
    API -- "structured JSON" --> MCP
    MCP -- "typed response + suggestions" --> AI

    style AI fill:#09090b,stroke:#4ade80,color:#fafafa
    style MCP fill:#09090b,stroke:#fafafa,color:#fafafa
    style API fill:#09090b,stroke:#3f3f46,color:#a1a1aa
    style DB fill:#09090b,stroke:#3f3f46,color:#a1a1aa

服务会将工具调用转换为 REST API 请求，并处理身份验证、速率限制（遇到 429 时自动退避重试）、分页和错误映射。

两种传输方式：

• stdio（本地）——使用 FRIHET_API_KEY 运行 npx @frihet/mcp-server
• Streamable HTTP（远程）——使用 Bearer 令牌或 OAuth 2.0+PKCE 访问 https://mcp.frihet.io/mcp

环境变量

变量	必需	默认值
FRIHET_API_KEY	是（stdio）	--
FRIHET_API_URL	否	https://api.frihet.io/v1
FRIHET_TOOL_MODE	否	full
FRIHET_CLAUDE_MODE	否（尚未发布的本地候选版本）	false

仅包含源代码的 Claude 候选版本需要构建此代码库并运行 dist/index.js；现有 npm 发布版本并未声称支持该标志。 请参阅候选版本的范围、排除项和检查项。 它不能与 FRIHET_OPENAI_MODE=true 同时使用，也未在已部署的 Worker 中启用。

工具暴露：按需提供深度

Frihet 的差异化优势在于深度——全面覆盖西班牙／欧盟税务，并原生支持合规要求（VeriFactu、TicketBAI、Facturae/FACe；波兰 KSeF 基础设施已就绪，等待启用）、银行业务、CRM、人力资源／薪资、住宿／PMS 和 POS。但如果一开始就把所有工具平铺加载到 Agent 的上下文中，就会造成 2026 年的上下文腐化问题：挤占任务所需空间，并在工作开始前就降低工具选择质量。

FRIHET_TOOL_MODE 可让你选择如何呈现这些深度。

模式	行为
full（默认）	以完整描述和架构暴露规范工具及税务别名。公开描述符会补充保守的可调用性和副作用信息；操作名称、架构和处理程序均不变。
grouped	渐进式披露。 每个工具的描述都会缩减为一行 [group] summary — full schema via describe_tool('name')，并添加三个轻量级发现工具。Agent 只需加载实际需要的工具详情。

在 grouped 模式下，操作名称、输入架构和处理程序均不变。描述符也会暴露与 full 配置相同的保守能力和操作信息。发现流程通过三个元工具实现：

• list_tool_groups() ——领域分类图（开票、费用、税务／合规、银行业务、CRM、人力资源／薪资、住宿／PMS、POS、智能分析、产品、平台），每个类别都附有一行简介和工具数量。
• search_tools(query) ——按工具名称、标题、摘要和分组进行全文搜索；返回匹配工具及其分组、摘要、只读标记和输入字段。可选的 group 筛选器和 limit 参数。
• describe_tool(name) ——在调用工具前，按需获取单个工具的完整原始描述和输入字段。

// claude_desktop_config.json — opt in to grouped mode
{
  "mcpServers": {
    "frihet": {
      "command": "npx",
      "args": ["@frihet/mcp-server"],
      "env": {
        "FRIHET_API_KEY": "fri_...",
        "FRIHET_TOOL_MODE": "grouped"
      }
    }
  }
}

分组式暴露改变的是描述密度，而非操作行为。经过 OpenAI 审核的版本化配置会单独组合，并继续独立受控。

---

API 限制

限制	值
每分钟请求数	每个 API 密钥 100 次
每页结果数	最多 100 条（默认 50 条）
请求正文	最大 1 MB
Webhook 负载	最大 100 KB
每个账户的 Webhook 数	最多 20 个

速率限制会通过指数退避机制自动处理。

---

Claude Code 技能

除了原始 MCP 工具外，此仓库还包含一项 Claude Code 技能，用于补充业务上下文：西班牙税务规则、工作流示例、财务报告和自然语言命令。

安装技能

git clone https://github.com/Frihet-io/frihet-mcp.git
ln -s "$(pwd)/frihet-mcp/skills/frihet-mcp" ~/.claude/skills/frihet-mcp

也可以使用通用安装程序：

npx skills add Frihet-io/frihet-mcp

该技能会将请求路由到 Frihet MCP 工具（发票、报价、费用、客户、月度审查），并告知 Agent 在执行写入操作前何时需要请求确认。它不会添加独立的 /frihet 子命令，也不会附带 VAT 税率或可抵扣规则：税务数据来自你的 Frihet 数据，而非该技能。

完整文档：docs.frihet.io/desarrolladores/skill-claude-code

---

开发

git clone https://github.com/Frihet-io/frihet-mcp.git
cd frihet-mcp
npm install
npm run build

本地运行：

FRIHET_API_KEY=fri_xxx node dist/index.js

使用 MCP Inspector 进行测试：

npx @modelcontextprotocol/inspector node dist/index.js

---

参与贡献

欢迎贡献。请先创建 issue，讨论你希望进行的更改。

git clone https://github.com/Frihet-io/frihet-mcp.git
cd frihet-mcp
npm install
npm run build   # must pass before submitting

---

当前限制

• 不支持 OCR 或文件上传 ——MCP 处理的是结构化数据，不是图片或 PDF。
• 单个公司 ——一个 API 密钥对应一个 Frihet 工作区。
• 需要 Frihet 账户 ——你需要在 app.frihet.io 拥有有效账户和 API 密钥（以 fri_ 开头）。

---

生态

Package	说明
@frihet/mcp-server	此 MCP 服务（156 个规范操作 + 5 个别名；11 个本地资源；10 个提示词）
@frihet/sdk	TypeScript SDK（frihet.invoices.create()）
frihet	CLI（frihet invoices list --status overdue）
n8n-nodes-frihet	用于工作流自动化的 n8n 社区节点
REST API	位于 api.frihet.io/v1 的 OpenAPI 3.1
Remote MCP	部署在 Cloudflare Workers 上的托管端点（无需安装）
Webhooks	使用 HMAC-SHA256 的实时事件

链接

• Frihet -- 产品
• Documentation -- 完整文档
• API reference -- REST API
• MCP server docs -- 设置指南和故障排除
• npm -- 包注册表
• Smithery -- Smithery 市场
• MCP Registry -- 官方 Model Context Protocol 注册表
• GitHub MCP Registry -- Frihet 在 GitHub 上的条目
• Remote endpoint -- 托管的 MCP 服务（Cloudflare Workers）
• OpenAPI spec -- 机器可读的 API 定义
• Security policy -- 私密报告漏洞的指南

---

许可证

MIT。请参阅 LICENSE。

由 Frihet 构建。