Frihet MCP 是 Frihet ERP 的官方 MCP 服务器，用于将 AI 助手连接到 Frihet 企业管理系统。用户可以用自然语言创建发票、查询费用、管理客户、产品、报价、银行、CRM、HR/薪资与 POS 等业务数据。
用途 该服务器面向企业管理的 AI 原生操作，让 AI 助手在 IDE 或聊天客户端中直接创建、查询或修改 Frihet 中的业务记录。官方描述称其覆盖 AI 驱动的开票、税务与电子发票合规（VeriFactu、TicketBAI、Facturae）、银行、CRM、HR/薪资与 POS。
主要能力 目录包含 156 个规范操作，另有 5 个财税别名、10 个提示词。本地完整配置提供 161 个工具名、11 个资源、10 个提示词；托管分组配置提供 164 个工具名、7 个资源、10 个提示词；OpenAI 审核配置提供 33 个工具名、0 资源、0 提示词。目录成员资格并不保证每个工作区都启用了对应的后端 API。
操作类别包括：CRM 联系人（3）、CRM 活动（2）、智能（4）、电子发票（10）、时间跟踪（6）、定期发票（8）、团队管理（4）、Gestoria 会计师（5）、白标门户域名（3）、自助入驻与 VIES（2）、IGIC 加那利群岛间接税（4）、公司税（2）、银行分类规则（2）、西班牙税务模型（7）、度假租赁/住宿（5）、POS 销售点（4）、厨房/餐厅（6）、HR 人力资源（9）、权限（2）、期间结算（3）。Onboarding 相关工具已通过 #124 撤回，因为 Frihet-ERP /v1/onboarding/* 系列在当前版本不存在。
使用方式 支持两种传输方式：本地 stdio 使用 npx @frihet/mcp-server 并设置 FRIHET_API_KEY；远程 Streamable HTTP 使用 https://mcp.frihet.io/mcp，支持 Bearer token 或 OAuth 2.0+PKCE。远程端点托管在 Cloudflare Workers 上，无需本地依赖。
安装方式包括：Claude Code 插件（同时安装业务管理技能与 MCP 服务器，技能调用为 /frihet-erp:frihet-mcp，捆绑的 .mcp.json 通过 npx 启动 @frihet/mcp-server）；Claude Code 一条命令；Codex CLI 一条命令（Codex 配置为 TOML，需使用 codex mcp add，不能直接粘贴 JSON）；Claude Desktop、Cursor、Windsurf、Cline 使用相同的 JSON 配置，仅文件路径不同。
获取 API 密钥：登录 app.frihet.io，进入 Settings > API，点击 Create API key，复制以 fri_ 开头的密钥（仅显示一次）。
演示模式 无需注册、无需 API 密钥即可试用。演示模式下服务器从真实感示例数据（西班牙发票含 IVA/IGIC、费用、客户、产品、银行账户等）返回结果，所有记录使用 demo_ 前缀 ID，启动时打印 DEMO MODE 横幅。不持久化任何数据，不发起网络调用。写入为模拟，财税动作（电子发票、VeriFactu、TicketBAI、FACe、薪资）返回明确标注的模拟结果，绝不向任何税务机关真实提交。
契约规则 官方描述强调三条规则：行动前先定位，使用 get_business_context 和 frihet://tax/rates 资源决定正确的税务处理，不要凭记忆回忆西班牙税率；草稿、展示、停止，create_invoice、create_quote 和 create_credit_note 默认 status=draft，不生成财税编号、不生成哈希、不向税务机关发送任何内容，展示草稿后交还用户；人类权威不可代为假设，任何具有非空 externalSideEffects 的工具会触达客户收件箱、webhook、资金或 AEAT/VeriFactu/TicketBAI/FACe，部分工具还需 confirm=true，该标志记录人类决定，绝不应为满足自身计划而设置。
资源与提示词 本地包提供 11 个资源：7 个静态参考资源加 4 个 API 支持的账户资源。托管 Worker 仅提供 7 个静态资源。OpenAI 审核主机提供 0 个资源。静态资源为参考数据，不调用 API；动态资源为账户实时数据。
工具暴露模式 FRIHET_TOOL_MODE 可选择工具暴露方式。分组模式下操作名称、输入模式和处理程序不变，发现流程通过三个元工具：list_tool_groups() 返回领域地图（开票、费用、财税/合规、银行、CRM、HR/薪资、住宿/PMS、POS、智能、产品、平台）及每个领域的一行简介和工具数量；search_tools(query) 在工具名称、标题、摘要和分组中进行自由文本搜索，返回匹配工具及其分组、摘要、只读标志和输入字段，可选 group 过滤和 limit；describe_tool(name) 按需返回单个工具的完整原始描述和输入字段。分组暴露改变的是描述密度，不是操作行为。
能力与副作用真实性 在完整 MCP 表面上，每个 tools/list 条目包含 _meta["io.frihet/capability"]：registered 表示名称和处理程序存在于当前服务器构建中；callability 为 api_dependent（处理程序调用 API，部署、工作区启用和授权仍决定结果）、runtime_checked（处理程序明确区分后端缺失与空数据）、deferred、unavailable 或 local，绝不无条件声称“可用”；writesFrihet、externalInteraction 和 externalSideEffects 区分状态变更与对外部实体/提供商的调用；MCP 动作注解仍是只读、破坏性、幂等和开放世界提示的标准来源。
ChatGPT/OpenAI 主机是单独审核的表面：恰好 33 个业务操作，描述完整，0 个发现元工具、0 个提示词、0 个资源。其 17 个读取和 16 个写入刻意收窄，所有写入要求字面 confirm=true。十个写入可向工作区所有者先前配置的活动端点投递完整业务事件；webhook 管理本身仍被排除。直接邮件投递、旧版月度摘要、原始发票 PDF、发票生命周期转换、更新现有报价、受监管申报、删除客户父记录、删除带链接文件的费用、删除产品、删除供应商也被排除。该表面不得从完整目录推断。
Claude Code 技能 除原始 MCP 工具外，仓库还包含一个 Claude Code 技能，增加业务上下文：西班牙税务规则、工作流配方、财务报告和自然语言命令。该技能了解 IVA 税率、IRPF 预扣、Modelo 303 准备、费用可抵扣规则和 VeriFactu 合规。
适用场景 适用于需要在 AI 助手中以自然语言操作 Frihet ERP 的企业用户，包括开票、费用管理、客户与产品管理、银行、CRM、HR/薪资、POS 等。支持 Claude、ChatGPT、Cursor、Windsurf、Cline、Antigravity、Codex、Copilot、Gemini CLI 及任何兼容 MCP 的客户端。
限制 不支持 OCR 或文件上传，MCP 处理结构化数据，不处理图像或 PDF。如需数字化纸质发票或收据，需先提取数据（如 Claude Vision API、专用 OCR 服务或手动录入），再用 MCP 创建记录。不支持文件上传或附件处理，不支持任何图像处理。单公司：一个 API 密钥映射一个 Frihet 工作区。需要 Frihet 账户：需在 app.frihet.io 有活跃账户和以 fri_ 开头的 API 密钥。速率限制自动处理，429 时使用指数退避重试。
许可 MIT，详见 LICENSE。由 Frihet 构建。
