india-stack-mcp

MCP servers that let AI agents work with Indian accounting and tax systems: TallyPrime, Zoho Books and GST. They work in Claude Desktop, Claude Code, Cursor, Codex or any MCP client.

Frontier agents can reason about GST, but they cannot touch Tally: there is no modern API, just a local XML gateway with its own conventions. This project is the connector layer: typed tools, dry-run-first writes, idempotency, human approval for destructive actions, and a tamper-evident audit trail.

Status

Related MCP server: TallyPrime MCP Server

Quick start

git clone https://github.com/rishiksaib/india-stack-mcp
cd india-stack-mcp
npm install
npm run build

Point your MCP client at the built servers (see examples/claude_desktop_config.json):

{
  "mcpServers": {
    "tally": {
      "command": "node",
      "args": ["<abs-path>/packages/connector-tally/bin/tally-mcp.js"],
      "env": {
        "TALLY_URL": "http://localhost:9000",
        "TALLY_COMPANY": "Your Company Pvt Ltd",
        "INDIA_STACK_AUDIT_LOG": "<abs-path>/audit/tally-audit.jsonl"
      }
    },
    "zoho": {
      "command": "node",
      "args": ["<abs-path>/packages/connector-zoho/bin/zoho-mcp.js"],
      "env": {
        "ZOHO_CLIENT_ID": "...",
        "ZOHO_CLIENT_SECRET": "...",
        "ZOHO_REFRESH_TOKEN": "...",
        "ZOHO_DC": "in",
        "ZOHO_ORGANIZATION_ID": "...",
        "INDIA_STACK_AUDIT_LOG": "<abs-path>/audit/zoho-audit.jsonl"
      }
    },
    "gst": {
      "command": "node",
      "args": ["<abs-path>/packages/connector-gst/bin/gst-mcp.js"]
    }
  }
}

Tally: TallyPrime running on the same machine with XML serving enabled on port 9000 (F1 → Settings → Connectivity). See docs/tally-xml-notes.md.

Zoho Books: a self-client OAuth refresh token with Books scopes (ZohoBooks.fullaccess.all or narrower) from the Zoho API Console. Use ZOHO_DC=in for India accounts.

Conventions every tool follows

• Amounts: positive = debit, negative = credit. Rent paid from the bank is Rent +25000, HDFC Bank -25000. The Tally client converts to Tally's own XML signs.

• Writes preview first. Every write returns the exact upstream request (and, for Tally vouchers, a debit/credit summary) until you pass dry_run: false.

• Retries are safe with a key. Pass an idempotency_key on committed writes; a retry with the same key returns the first result instead of posting again, even after a restart. Writes without a key are never merged, so two genuine identical entries both post.

• Destructive actions need a human. Deleting a voucher opens a confirmation dialog in the MCP client. If the client can't show one, the call is refused unless INDIA_STACK_DESTRUCTIVE=allow is set.

Tools (28)

Tally (13). Reads: tally_list_companies, tally_get_company, tally_search_ledgers, tally_get_ledger, tally_ledger_balances, tally_trial_balance (with debit/credit totals and difference), tally_day_book, tally_find_vouchers (with master_id), tally_list_voucher_types, tally_purchase_register (supplier GSTIN, bill number, taxable value and tax split, ready for gst_reconcile_2b). Writes: tally_create_ledger, tally_create_voucher (Sales, Purchase, Payment, Receipt, Journal, Contra, Credit Note, Debit Note; returns master_id), tally_delete_voucher (approval required).

Zoho Books (11). Reads: zoho_list_organizations, zoho_list_contacts, zoho_get_contact, zoho_list_invoices, zoho_get_invoice, zoho_list_items, zoho_chart_of_accounts. Writes (dry-run by default): zoho_create_contact (GSTIN as gst_no, gst_treatment, state), zoho_create_invoice (place_of_supply, per-line tax_id and hsn_or_sac), zoho_create_item, zoho_create_customer_payment.

GST (4). gst_validate_gstin (mod-36 checksum, state, PAN, holder type); gst_einvoice_build (schema v1.1 JSON: IsServc, place of supply, IGST vs CGST+SGST by place of supply, SEZ/export with and without payment, rates including 40%, optional rupee round-off); gst_einvoice_generate (dry-run only unless an IRP integration exists; it never returns a fake IRN); gst_reconcile_2b (exact and fuzzy matching, value/tax mismatches, missing either side, credit notes, cess, and ITC that 2B marks as not available).

There is no licensed IRP/GSP client in this package. Build the JSON with gst_einvoice_build and upload it through the e-invoice portal or your GSP.

Environment variables

Safety model

• Writes default to preview; committing requires dry_run: false.

• Vouchers are balance-checked client-side before any network call.

• Tally import responses are checked properly: ERRORS count, LINEERROR, and that something was actually created, altered or deleted.

• Every call appends a redacted, hash-chained audit record. Secrets, PAN, GSTIN, card and Aadhaar numbers are masked; company names and record IDs are kept.

• A write that times out is reported as "outcome unknown" so the agent checks before retrying.

See docs/architecture.md for the design.

HTTP mode

npm run start -w @india-stack/demo-host   # POST http://127.0.0.1:8787/mcp/tally

Binds to 127.0.0.1 by default and checks the Host header. To expose it beyond this machine set HOST and INDIA_STACK_HTTP_TOKEN (16+ characters); every request then needs Authorization: Bearer <token>. Add extra host names with INDIA_STACK_ALLOWED_HOSTS.

Development

npm run test        # unit, recorded TallyPrime 7.2 responses, and MCP protocol-level tests
TALLY_COMPANY="Test Co" LIVE_DATE=2026-04-02 node evals/live/tally-live.mjs   # end-to-end on a real TallyPrime (use an empty test company)
npm run lint && npm run typecheck && npm test

License

Apache-2.0