Obolus

Obolus Finance API 和远程 MCP 示例

Obolus 薪资和多国税务 API 的公开示例。本仓库包含一个小型 Vite 客户端、连接示例和文档。托管的计算引擎和 MCP 服务运行于 obolusfinanz.de；其服务端源代码不包含在本仓库中。

远程 MCP 服务

Obolus 提供一个公开的只读 MCP 端点：

• Streamable HTTP：https://www.obolusfinanz.de/api/mcp/claude
• 工具：berechne 用于详细的单国薪资计算，taxcompare 用于比较两个或更多国家
• 访问：这些只读工具无需登录或 API 密钥
• 注册表：io.github.sanzation/obolus
• 完整 API 和 MCP 文档：Obolus Developers

尽管 /claude 是历史路由名称，但该 URL 提供的是与 Agent 无关的 MCP 接口。它适用于 Claude 以外的 MCP 客户端。此接口与面向浏览器的 ChatGPT 应用集成（位于 /api/mcp）相互独立。

从 VS Code / GitHub Copilot 连接

本仓库包含一个 工作区 .mcp.json。在 VS Code 中打开此文件夹，打开 MCP 服务列表，然后启动 obolus。你也可以将其配置复制到自己的工作区：

{
  "servers": {
    "obolus": {
      "type": "http",
      "url": "https://www.obolusfinanz.de/api/mcp/claude"
    }
  }
}

例如，可以向 Agent 提问：“使用 Obolus 比较德国和奥地利在 2026 纳税年度、年税前工资为 EUR 60,000 时的情况。”如果缺少个人资料信息，Agent 应该询问，而不是凭空编造。计算结果仅为估算；使用结果前，请检查各工具返回的假设和来源信息。

若要检查公开 MCP 连接而不执行计算，请运行 npm run mcp:check。此命令会列出可用工具，并检查预期的两个工具是否都存在。

REST API 演示

Vite 应用演示了对 POST /api/berechne 和 POST /api/taxcompare 的直接 REST 调用。它是一个 API 客户端，并非本地 MCP 服务或税务引擎的副本。

npm install
npm run dev

打开 http://localhost:8080。Vite 代理会转发 API 请求；请参阅 vite.config.js。使用 npm run build 进行构建。

如需了解当前完整的请求架构和响应示例，请参阅开发者页面或 OpenAPI 文档。浏览器演示使用以主要货币单位计价的旧版 annual_gross 别名。新的 taxcompare 集成应优先使用以次要货币单位计价的 salary_ct：当 currency 为 eur 且 salary_period 为 annual 时，6000000 表示 EUR 60,000。必须至少提供两个国家和一个受支持的纳税年度。详细的 berechne 端点的工资字段也使用次要货币单位。

比较请求示例：

const response = await fetch("https://www.obolusfinanz.de/api/taxcompare", {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({
    salary_ct: 6000000,
    salary_period: "annual",
    tax_year: "2026",
    countries: ["DE", "AT"],
    currency: "eur"
  })
});
if (!response.ok) throw new Error(await response.text());
const result = await response.json();
console.log(result);

支持的国家：德国、奥地利、瑞士、美国、英国、爱尔兰、加拿大和澳大利亚。返回的净工资是税务／薪资计算结果。住房、食品杂货、薪资扣缴范围之外的医疗费用以及购买力调整属于独立模型；不要将薪资净额描述为扣除生活成本后的可支配收入。

仓库范围和使用方式

这是一个公开的集成示例，不是 MCP 服务的源代码仓库。托管 API 设有使用条款和速率限制；不要认为此演示可用于不受限制的生产访问。请勿提交 API 密钥或其他凭据。公开的只读 MCP 工具无需密钥。