Angaria

Angaria MCP

English | 土耳其语

Angaria 是一款用于土耳其电子归档发票的 Mac 应用。它取代了土耳其税务机关 GİB 的电子归档门户网页：你可以在一个原生应用中创建发票，使用 GİB 发送到你手机上的短信验证码为发票签名，并下载发票。Angaria 运行时还会启动一个 MCP 服务，让 Claude、Cursor、Codex 和其他 AI 助手创建、签名和下载发票，并管理你的客户和服务。

此代码库包含 angaria-mcp，这是一个小型开源程序，可将仅运行本地程序的 MCP 客户端（Claude Desktop）连接到该服务。代码库还包含 MCP 目录会读取的文件。MCP 服务本身内置于 Angaria 应用中，且仅在应用运行时可用。关闭 Angaria 后，没有任何服务在监听，所有请求都会返回错误“无法连接到 Angaria。请打开 Angaria。”（"Could not connect to Angaria. Open Angaria."）。

网站：angaria.app/en

要求

• 搭载 macOS 11 或更高版本的 Mac。
• 已安装并打开的 Angaria 应用，并拥有许可证或 7 天免费试用资格。Angaria 是一款付费应用。
• GİB 电子归档门户账户（用户代码和密码），并已保存在 Angaria 中。
• 在 GİB 注册的手机。为发票签名需要输入 GİB 发送到该手机上的短信验证码。

Angaria 应用使用土耳其语。工具会用土耳其语回复，你的助手可以进行翻译。

设置

最快的方法：打开 Angaria，进入 MCP 页面，然后使用 Kurulum。其 Kurulum 部分列出了 22 个客户端，包括 Claude Code、Claude Desktop、Codex、Cursor、Gemini CLI、VS Code、Windsurf 和 Zed；点击一次 Ekle，即可将 Angaria 添加到各个客户端。

手动设置时，每个客户端使用相同的地址：http://127.0.0.1:41234/mcp（Streamable HTTP，无需密钥）。

Claude Code

claude mcp add --transport http --scope user angaria http://127.0.0.1:41234/mcp

Cursor

在 ~/.cursor/mcp.json 中：

{"mcpServers":{"angaria":{"url":"http://127.0.0.1:41234/mcp"}}}

Codex

在 ~/.codex/config.toml 中：

[mcp_servers.angaria]
url = "http://127.0.0.1:41234/mcp"

其他客户端

支持按类型和 URL 配置 Streamable HTTP 服务的客户端，添加以下条目，并将其命名为 angaria：

{"type":"http","url":"http://127.0.0.1:41234/mcp"}

Claude Desktop

Claude Desktop 只能运行本地程序（stdio 服务），因此需要 angaria-mcp。Angaria 应用已内置该程序。在 ~/Library/Application Support/Claude/claude_desktop_config.json 中：

{
  "mcpServers": {
    "angaria": {
      "command": "/Applications/Angaria.app/Contents/MacOS/angaria-mcp"
    }
  }
}

请将 Angaria 保留在“应用程序”文件夹中。如果从“下载”文件夹或磁盘映像打开它，macOS 会从临时位置运行该应用，导致此路径失效。

你也可以从此代码库构建 angaria-mcp，并改用构建产物的路径。发布版本后，其中的 angaria-mcp.mcpb 文件可通过双击在 Claude Desktop 中安装同一程序。

工具

以下工具按服务列出的顺序排列。标记为“Yes”的工具仅在 Angaria 的 MCP 页面中开启“Ajanlar onaylayabilir ve silebilir”（“Agent 可以签署和删除”）后才能使用。该开关默认关闭。关闭时，这些工具仍会保留在列表中，但会返回一条指出该开关名称的错误消息，以便助手告知你需要开启什么。

工具	功能	需要开启开关
list_invoices	列出两个日期之间（最多 31 天）的发票，并按状态和收件人筛选。
get_invoice	获取发票的收件人、明细和总额，或 GİB 对发票的原始视图。
create_invoice	按照应用中新建发票表单的相同规则创建未签署的发票草稿。
duplicate_invoice	基于现有发票创建一份日期为今天的新草稿。
download_invoice	将 Angaria PDF、e-Arşiv PDF 或 GİB ZIP 文件保存到你的“下载”文件夹。
request_signing_sms	请求 GİB 向你的手机发送短信验证码，以便签署草稿。	是
sign_invoices	使用你提供给 Agent 的短信验证码签署草稿。签署后的发票即为最终版本。	是
delete_draft	从 GİB 删除未签署的草稿。绝不会影响已签署的发票。	是
list_customers	列出已保存的客户及其发票默认设置。
get_customer	获取客户详情及发票默认设置。
create_customer	保存新客户。
update_customer	修改客户详情或发票默认设置。
delete_customer	删除已保存的客户。已开具的发票不会改变。	是
list_services	列出已保存的服务及其价格、货币和增值税税率。
get_service	获取服务的价格、单位和增值税税率。
create_service	保存新服务。
update_service	修改服务名称、价格或增值税税率。
delete_service	删除已保存的服务。已开具的发票不会改变。	是
list_companies	列出 Angaria 中的公司，以及当前选中的公司。
get_company_details	获取 PDF 上显示的公司和银行详情，以及 PDF 设计。
update_company_details	修改 PDF 上显示的公司和银行详情，包括 IBAN。	是
rename_company	修改 Angaria 公司列表中显示的公司名称。	是
set_company_logo	将 PDF 标志替换为 Mac 上的图像文件，或移除标志。	是
get_exchange_rate	获取土耳其中央银行（TCMB）在发票日期的买入汇率。
check_gib_connection	使用已保存的用户代码登录 GİB，然后退出。密码不会发送给 Agent。
lookup_taxpayer	从 GİB 获取土耳其税号（VKN 或 TCKN）对应的注册名称和税务局。
close_gib_session	关闭仍在 e-Arşiv Portal 中打开的会话。	是
scan_gib_import	从已签署的发票中查找可保存的客户和服务。
apply_gib_import	保存你从扫描结果中选定的客户和服务。绝不会修改已保存的项目。
get_app_settings	获取主题、调色板和 Angaria 版本。
update_app_settings	修改主题或调色板。

示例

为 Apple 开具一张 $5,000 的服务出口发票

助手会在已保存的客户中查找 Apple（或将其添加进去），然后创建一份以美元计价的草稿，发票类型为 İstisna（免征增值税，因为这是销往国外的服务），并使用发票日期对应的 TCMB 买入汇率。你可以在 Angaria 中查看草稿。若要在聊天中签署，请开启该开关，请助手签署，并提供 GİB 发送到你手机上的短信验证码。

安全性

• 服务仅在这台 Mac 上监听（127.0.0.1）。对于 Host 不是其端口上的本地地址的请求，以及任何带有 Origin 标头的请求，服务都会拒绝，因此网页无法访问它。
• 服务没有密钥。Angaria 打开时，这台 Mac 上的任何程序都可以访问服务。Angaria 关闭时，没有任何服务在监听。
• 签名始终需要 GİB 发送到你手机上的短信验证码。没有你提供的验证码，助手无法签名。
• 只有在启用「Ajanlar onaylayabilir ve silebilir」时，签名、删除和更改公司详情（每份 PDF 上的 IBAN）才会生效。此选项默认关闭。
• 你的 GİB 密码保存在 macOS Keychain 中。没有任何工具会读取或写入该密码。
• Angaria 没有账户，也没有云存储。你的发票、客户和服务都保存在你的 Mac 上。此应用只会与 GİB、TCMB（用于汇率）、Polar（用于许可证）以及 Angaria 的更新服务通信。
• Angaria 的 MCP 页面会在活动日志中列出每次工具调用，并遮蔽短信验证码和密码。

从源代码构建

你需要 macOS 和 Rust。rust-toolchain.toml 会安装两个 Mac 目标平台。

cargo test
cargo build --release

程序位于 target/release/angaria-mcp。若要为 Apple 芯片和 Intel 构建通用二进制文件，并打包 dist/angaria-mcp.mcpb（打包需要 Node 和 npx）：

./scripts/build.sh

SKIP_PACK=1 ./scripts/build.sh 仅构建通用二进制文件，生成位置为 dist/angaria-mcp。

angaria-mcp 从标准输入读取 JSON-RPC 消息，每行一条，将每条消息发送到 http://127.0.0.1:41234/mcp，并将每条响应写入标准输出。它不会读取任何文件，也不会打开 Angaria。

许可证

本仓库中的代码采用 MIT 许可证。Angaria 应用本身是专有付费软件；其源代码不公开。