Angaria

Angaria MCP

English | Türkçe

Angaria is a Mac app for Turkish e-Arşiv invoicing. It replaces the web pages of GİB's e-Arşiv Portal (GİB is the Turkish tax authority): you create invoices, sign them with the SMS code GİB sends to your phone, and download them from one native app. While Angaria is open, it also runs an MCP server, so Claude, Cursor, Codex and other AI assistants can create, sign and download your invoices and manage your customers and services.

This repository holds angaria-mcp, a small open source program that connects MCP clients which only run local programs (Claude Desktop) to that server. It also holds the files MCP directories read. The MCP server itself lives inside the Angaria app and works only while the app is open. When Angaria is closed, nothing listens, and every request gets the error "Angaria’ya bağlanılamadı. Angaria’yı aç." ("Could not connect to Angaria. Open Angaria.").

Website: angaria.app/en

Requirements

• A Mac with macOS 11 or later.
• The Angaria app, installed and open, with a license or the 7-day free trial. Angaria is a paid app.
• A GİB e-Arşiv Portal account (user code and password), saved in Angaria.
• The phone registered with GİB. Signing an invoice needs the SMS code GİB sends to it.

The Angaria app is in Turkish. The tools answer in Turkish, and your assistant can translate.

Setup

The fastest way: open Angaria, go to the MCP page, and use Kurulum. Its Kurulum section lists 22 clients, among them Claude Code, Claude Desktop, Codex, Cursor, Gemini CLI, VS Code, Windsurf and Zed, and adds Angaria to each one with one click (Ekle).

By hand, every client gets the same address: http://127.0.0.1:41234/mcp (Streamable HTTP, no key).

Claude Code

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

Cursor

In ~/.cursor/mcp.json:

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

Codex

In ~/.codex/config.toml:

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

Other clients

A client that takes Streamable HTTP servers by type and URL gets this entry, named angaria:

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

Claude Desktop

Claude Desktop runs only local programs (stdio servers), so it needs angaria-mcp. The Angaria app already contains it. In ~/Library/Application Support/Claude/claude_desktop_config.json:

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

Keep Angaria in your Applications folder. If you open it from Downloads or from the disk image, macOS runs it from a temporary location, and that path stops working.

You can also build angaria-mcp from this repository and use the path of your build instead. When a release is published, its angaria-mcp.mcpb file installs the same program in Claude Desktop with a double click.

Tools

The tools in the order the server lists them. A tool marked "Yes" works only when "Ajanlar onaylayabilir ve silebilir" ("Agents can sign and delete") is on in Angaria's MCP page. That switch is off by default. While it is off, these tools stay in the list and answer with an error that names the switch, so your assistant can tell you what to turn on.

Example

Invoice Apple for $5,000, service export

The assistant finds Apple in your saved customers (or adds it), then creates a draft in US dollars as an İstisna invoice (exempt from VAT, as services sold abroad are), with the TCMB buying rate for the invoice date. You see the draft in Angaria. To sign it from the chat, turn on the switch, ask the assistant to sign, and give it the SMS code GİB sends to your phone.

Safety

• The server listens only on this Mac (127.0.0.1). It refuses a request whose Host is not a local address on its port, and any request with an Origin header, so web pages cannot reach it.
• There is no key. While Angaria is open, any program on this Mac can reach the server. When Angaria is closed, nothing listens.
• Signing always needs the SMS code GİB sends to your phone. The assistant cannot sign without the code you give it.
• Signing, deleting and changing company details (the IBAN on every PDF) work only when "Ajanlar onaylayabilir ve silebilir" is on. It is off by default.
• Your GİB password stays in the macOS Keychain. No tool reads or writes it.
• Angaria has no account and no cloud storage. Your invoices, customers and services stay on your Mac. The app talks only to GİB, TCMB (for exchange rates), Polar (for the license) and Angaria's update server.
• Angaria's MCP page lists every tool call in an activity log, with SMS codes and passwords masked.

Build from source

You need macOS and Rust. rust-toolchain.toml installs both Mac targets.

cargo test
cargo build --release

The program is at target/release/angaria-mcp. To build the universal binary for Apple silicon and Intel and pack dist/angaria-mcp.mcpb (packing needs Node with npx):

./scripts/build.sh

SKIP_PACK=1 ./scripts/build.sh builds only the universal binary, at dist/angaria-mcp.

angaria-mcp reads JSON-RPC messages from standard input, one per line, sends each to http://127.0.0.1:41234/mcp, and writes each answer to standard output. It reads no file and never opens Angaria.

License

The code in this repository is under the MIT License. The Angaria app itself is proprietary and paid; its source is not public.