Angaria

Angaria MCP

English | Türkçe

Angaria は、トルコの e-Arşiv 請求書発行用の Mac アプリです。GİB の e-Arşiv Portal のウェブページ（GİB はトルコの税務当局）に代わるもので、請求書の作成、GİB から電話に届く SMS コードでの署名、ダウンロードを、ひとつのネイティブアプリで行えます。Angaria を開いている間は MCP サーバーも実行されるため、Claude、Cursor、Codex などの AI アシスタントが請求書を作成、署名、ダウンロードしたり、顧客やサービスを管理したりできます。

このリポジトリには、ローカルプログラムのみを実行する MCP クライアント（Claude Desktop）をそのサーバーに接続する小さなオープンソースプログラム、angaria-mcp が含まれています。また、MCP ディレクトリが読み込むファイルも含まれています。MCP サーバー自体は Angaria アプリに内蔵されており、アプリが開いている間のみ動作します。Angaria を終了すると、リクエストを受け付けるものはなくなり、すべてのリクエストに「Angaria’ya bağlanılamadı. Angaria’yı aç.」（「Angaria に接続できませんでした。Angaria を開いてください。」）というエラーが返されます。

ウェブサイト：angaria.app/en

必要条件

• macOS 11 以降を搭載した Mac。
• Angaria アプリをインストールして起動していること。ライセンス、または 7 日間の無料トライアルが必要です。Angaria は有料アプリです。
• GİB e-Arşiv Portal のアカウント（ユーザーコードとパスワード）があり、Angaria に保存されていること。
• GİB に登録した電話。請求書への署名には、GİB からその電話に届く SMS コードが必要です。

Angaria アプリはトルコ語です。ツールの応答もトルコ語ですが、アシスタントで翻訳できます。

セットアップ

最も簡単な方法は、Angaria を開き、MCP ページに移動して、Kurulum を使うことです。Kurulum セクションには Claude Code、Claude Desktop、Codex、Cursor、Gemini CLI、VS Code、Windsurf、Zed など 22 のクライアントが一覧表示され、それぞれにワンクリック（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 は Applications フォルダに置いてください。Downloads またはディスクイメージから開くと、macOS はアプリを一時的な場所から実行するため、そのパスは使えなくなります。

このリポジトリから angaria-mcp をビルドすることもでき、その場合はビルドしたプログラムのパスを使用します。リリースが公開されると、リリース内の angaria-mcp.mcpb ファイルをダブルクリックするだけで、Claude Desktop に同じプログラムをインストールできます。

ツール

サーバーが一覧表示する順にツールを記載しています。「はい」と表示されているツールは、Angaria の MCP ページで「Ajanlar onaylayabilir ve silebilir」（「エージェントが署名および削除できる」）をオンにした場合のみ動作します。このスイッチはデフォルトでオフです。オフの間もこれらのツールは一覧に表示され、スイッチの名前を示すエラーを返すため、アシスタントはオンにする設定を案内できます。

ツール	機能	スイッチが必要
list_invoices	2 つの日付の間（最大 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 に SMS コードを携帯電話へ送信するよう依頼します。	はい
sign_invoices	エージェントに伝えた SMS コードを使って下書きに署名します。署名済みの請求書は確定となります。	はい
delete_draft	GİB から未署名の下書きを削除します。署名済みの請求書には一切触れません。	はい
list_customers	保存済みの顧客と、それぞれの請求書のデフォルト設定を一覧表示します。
get_customer	顧客の詳細と請求書のデフォルト設定を取得します。
create_customer	新しい顧客を保存します。
update_customer	顧客の詳細または請求書のデフォルト設定を変更します。
delete_customer	保存済みの顧客を削除します。発行済みの請求書は変更されません。	はい
list_services	保存済みのサービスを、価格、通貨、VAT 税率とともに一覧表示します。
get_service	サービスの価格、単位、VAT 税率を取得します。
create_service	新しいサービスを保存します。
update_service	サービスの名前、価格、または VAT 税率を変更します。
delete_service	保存済みのサービスを削除します。発行済みの請求書は変更されません。	はい
list_companies	Angaria に登録されている会社と、選択中の会社を一覧表示します。
get_company_details	PDF に印刷される会社情報と銀行情報、および PDF のデザインを取得します。
update_company_details	IBAN を含む、PDF に印刷される会社情報と銀行情報を変更します。	はい
rename_company	Angaria の会社一覧に表示される会社名を変更します。	はい
set_company_logo	Mac 上の画像ファイルで PDF のロゴを置き換えるか、ロゴを削除します。	はい
get_exchange_rate	請求書の日付におけるトルコ中央銀行（TCMB）の買いレートを取得します。
check_gib_connection	保存済みのユーザーコードで GİB にログインし、その後ログアウトします。パスワードがエージェントに送信されることはありません。
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 を見つけ（または追加し）、トルコ中央銀行（TCMB）の請求書発行日の買いレートを適用して、米ドル建ての İstisna 請求書（海外で販売されるサービスは VAT 免税）を下書きとして作成します。下書きは Angaria で確認できます。チャットから署名するには、スイッチをオンにしてアシスタントに署名を依頼し、GİB から携帯電話に送信された SMS コードを伝えてください。

安全性

• サーバーはこの Mac 上（127.0.0.1）でのみ待ち受けます。Host がそのポートのローカルアドレスでないリクエストと、Origin ヘッダーを含むすべてのリクエストを拒否するため、Web ページからアクセスすることはできません。
• キーはありません。Angaria が起動している間は、この Mac 上のどのプログラムからでもサーバーにアクセスできます。Angaria を終了すると、待ち受けるものは何もありません。
• 署名には常に、GİB から携帯電話に送信される SMS コードが必要です。アシスタントが署名できるのは、あなたがコードを渡した場合のみです。
• 署名、削除、および会社情報の変更（すべての PDF に記載される IBAN）は、「Ajanlar onaylayabilir ve silebilir」がオンの場合にのみ機能します。デフォルトではオフです。
• GİB のパスワードは macOS キーチェーンに保存されます。どのツールもパスワードを読み取ったり書き込んだりしません。
• Angaria にはアカウントもクラウドストレージもありません。請求書、顧客、サービスは Mac 上に保存されます。このアプリが通信するのは GİB、TCMB（為替レート用）、Polar（ライセンス用）、Angaria のアップデートサーバーのみです。
• Angaria の MCP ページには、SMS コードとパスワードをマスキングしたうえで、すべてのツール呼び出しがアクティビティログに記録されます。

ソースからビルドする

macOS と Rust が必要です。rust-toolchain.toml によって、両方の Mac ターゲットがインストールされます。

cargo test
cargo build --release

プログラムは target/release/angaria-mcp にあります。Apple シリコンと Intel の両方に対応するユニバーサルバイナリをビルドし、dist/angaria-mcp.mcpb にパッケージ化するには（パッケージ化には npx を含む Node が必要です）：

./scripts/build.sh

SKIP_PACK=1 ./scripts/build.sh を実行すると、dist/angaria-mcp にユニバーサルバイナリのみがビルドされます。

angaria-mcp は標準入力から JSON-RPC メッセージを1行ずつ読み取り、それぞれを http://127.0.0.1:41234/mcp に送信して、各応答を標準出力に書き込みます。ファイルを読み取ることはなく、Angaria を起動することもありません。

ライセンス

このリポジトリのコードは MIT License の下で提供されています。Angaria アプリ自体はプロプライエタリの有料製品であり、ソースコードは公開されていません。