# TallyPrime Connector for Claude (Unofficial)

Ask Claude about your TallyPrime books in plain English:

> "Who owes us money for more than 60 days?"
> "Show me the P&L for October and compare it with September."
> "How much GST do we owe for this month?"
> "Record a payment of ₹6,100 to Electricity Charges from Cash on 30 November."

The connector runs **only on your own Windows PC**, next to TallyPrime. It is free and open source, and the developer runs no servers.

**Current version: 1.0.5.** Reading and writing have both been tested on real TallyPrime. See [Verification status](#verification-status) and the [CHANGELOG](CHANGELOG.md) for every bug found and fixed along the way.

---

## Features

**Reports in plain English**
- **Trial balance, profit & loss and balance sheet** for any period, including a single month or a mid-year range.
- **Outstanding receivables and payables**, bill by bill, with ageing (0-30, 31-60, 61-90, 90+ days), overdue days and party totals.
- **GST summary**: taxable sales and purchases, output tax and input credit by CGST/SGST/IGST/cess, and net payable. Useful as a check before filing (it is not a return).
- **Ledger statements** with opening, running and closing balance, and **ledger search** by name or group.
- **Day Book** for up to a year at a time, with totals by voucher type.
- **Stock summary** with quantity, rate and value, flagging zero or negative stock.

**Figures you can trust**
- Period figures are calculated from your vouchers for **exactly the dates you ask**, so Tally's Educational Mode date quirks can't change them.
- **Built-in cross-check:** every ledger's total is compared with Tally's own balance, and any mismatch is named in the result rather than hidden.
- If Tally answers for a different date than the one asked, the result **says so**.

**Safe voucher entry (optional, off by default)**
- **Preview before saving.** It checks that every ledger exists (and suggests the right name for a typo), that debits equal credits, and that each GST amount matches the rate in the ledger's name. It also checks that CGST and SGST appear together, that the voucher type fits the ledgers, that the date isn't before the books begin, and that Educational Mode will accept the date.
- **Saves only after you confirm**, with a **duplicate guard** and a **local audit log**.
- Sales, Purchase, Payment, Receipt, Journal, Contra, Credit Note and Debit Note.

**Private by design**
- Runs entirely on your PC and talks only to Tally on `localhost`. No developer servers, accounts or tracking.

---

## ⚠️ Read this before you install

| | |
|---|---|
| **Unofficial** | This project is not made by, affiliated with, or endorsed by Tally Solutions Pvt. Ltd. "Tally" and "TallyPrime" are their trademarks and are used here only to describe compatibility. |
| **Not professional advice** | Nothing this connector or Claude says is accounting, tax or legal advice. For filing, compliance or audit decisions, your Chartered Accountant has the final word. |
| **AI can be wrong** | Claude can misread a question or summarise numbers incorrectly. For anything important (filing, payments, client reports), check the figure in Tally itself. |
| **GST figures are not your returns** | `tally_gst_summary` adds up your ledger balances. It is **not** GSTR-1 or GSTR-3B. Always verify with Tally's GST reports and the GST portal before filing. |
| **Your data goes to Claude** | The connector itself sends nothing to the developer. But the figures it reads become part of your Claude conversation, which is processed by Anthropic under [Anthropic's privacy policy](https://www.anthropic.com/legal/privacy). Don't use it on books you aren't allowed to share with a cloud AI service (check client agreements). |
| **Writing changes your books** | Writing is **off by default**. If you turn it on, **take a Tally backup first**, read every preview before approving, and never approve a voucher you didn't ask for. To undo an entry, delete or alter it in Tally. |
| **Keep Tally's port private** | Tally's XML port (usually 9000) has **no password**. Anyone who can reach it can read and change your books. Keep "Tally computer" set to `localhost` and never expose the port to the internet or public Wi-Fi. |

---

## What it can do (v1)

| Tool | What it does | Changes data? |
|---|---|---|
| `tally_check_connection` | Confirms Tally is reachable and lists loaded companies | No |
| `tally_search_ledgers` | Finds ledgers by name or group, with balances | No |
| `tally_outstanding` | Bill-wise receivables or payables with ageing (0-30, 31-60, 61-90, 90+ days) and party totals | No |
| `tally_trial_balance` | Trial balance for any period | No |
| `tally_profit_and_loss` | P&L for any period: sales, purchases, expenses, stock, gross and net profit | No |
| `tally_balance_sheet` | Balance sheet as on a date, with a balancing check | No |
| `tally_ledger_statement` | Every entry in one ledger with running balance | No |
| `tally_day_book` | Vouchers entered in a period, totals by type | No |
| `tally_gst_summary` | Output tax, input credit and net GST from your books | No |
| `tally_stock_summary` | Closing quantity, rate and value; flags zero or negative stock | No |
| `tally_preview_voucher` | Checks a voucher **without saving**: ledgers exist, debits = credits, GST rate looks standard, right voucher type | No |
| `tally_create_voucher` | Saves a Sales, Purchase, Payment, Receipt, Journal, Contra, Credit Note or Debit Note voucher | **Yes**. Only appears when writing is switched on |

---

## Requirements

- Windows 10 or 11
- TallyPrime (Silver or Gold), with the company you want to use **open**
- [Claude Desktop](https://claude.ai/download) on the **same PC**. The free plan works; a paid plan avoids hitting message limits, because each question can involve several calls to Tally.
- About 10 minutes

---

## Install

### 1. Turn on Tally's connector port

1. Open TallyPrime and load your company.
2. Press **F1 (Help) → Settings → Connectivity**.
3. Open **Client/Server configuration**.
4. Set **TallyPrime acts as** to **Both** (or **Server**).
5. Set **Port** to **9000** (or note the number you use).
6. Press **Ctrl+A** to save. Restart TallyPrime if it asks.

> On some versions the menu is **F1 → Settings → Advanced Configuration**, where you enable the HTTP server and set the port.

### 2. Install the extension

1. Download the latest `tallyprime-connector-<version>.mcpb` from the [Releases page](https://github.com/suhrith13/tallyprime-claude-connector/releases).
2. Double-click it. Claude Desktop opens and asks to install **TallyPrime Connector (Unofficial)**.
3. Click **Install**. Leave the settings as they are unless your port isn't 9000.

### 3. Check it works

In a new Claude chat, type:

> Check my Tally connection.

You should see your company name. If not, see [Troubleshooting](#troubleshooting).

---

## Settings

Open **Claude Desktop → Settings → Extensions → TallyPrime Connector**.

| Setting | Default | What it means |
|---|---|---|
| Tally port | `9000` | Must match Tally's Connectivity setting. |
| Tally computer | `localhost` | Keep this unless Tally runs on another PC **on a network you trust**. |
| Company name | empty | Empty = whichever company is open in Tally. Or type the exact company name. |
| Allow writing to Tally | **off** | Turn on to let Claude save vouchers (with preview and approval). |
| Keep a local log of changes | on | Every voucher sent to Tally is recorded in `%APPDATA%\TallyPrimeConnector\audit-log.jsonl` on this PC. |
| Timeout (seconds) | `30` | Increase for very large companies or long date ranges. |

---

## How writing works (if you turn it on)

1. You ask, e.g. *"Record today's sale to Rao Electricals: 20 MCB at ₹450 plus 18% GST."*
2. Claude finds the exact ledger names and calls **`tally_preview_voucher`**. Nothing is saved yet. The preview checks that:
   - every ledger exists (and suggests the right name if you made a typo),
   - total debit equals total credit,
   - CGST and SGST appear together, and IGST isn't mixed with them,
   - the GST rate is a standard one (0.25, 3, 5, 12, 18, 28 or 40%),
   - each tax ledger's amount matches the rate in its name (e.g. 9% of the taxable value for "Output CGST 9%"),
   - the voucher type makes sense (e.g. a Payment credits cash or bank),
   - the date isn't before the company's books begin, in the future, or very old,
   - in Educational Mode, the date is one Tally will accept (1st, 2nd or 31st).
3. Claude shows you the preview. **Read it.** Say yes only if every line is right.
4. Claude calls **`tally_create_voucher`**. Depending on your Claude Desktop tool-permission settings, it also asks you to allow the call. We recommend keeping this tool on "ask every time".
5. The voucher appears in Tally's **Day Book** for that date.

**Safety nets:**
- **Read-only by default.** The save tool doesn't even exist until you switch writing on.
- **Duplicate guard.** The same voucher can't be saved twice within 15 minutes unless you explicitly confirm. The guard resets when Claude Desktop restarts.
- **Timeouts are handled safely.** If Tally doesn't answer in time, Claude is told the voucher *may* have been saved and must not retry until you check the Day Book.
- **Tally's hidden errors are caught.** Tally answers "OK" even when it rejects an entry; the connector reads the reply and reports the real reason.
- **Local audit log** of every voucher sent to Tally: saved, rejected by Tally, or timed out. Entries stopped earlier by the preview checks or the duplicate guard are not logged.

**v1 writes accounting vouchers only** (ledger lines). It does not post item-wise inventory invoices, create or edit ledgers, or delete anything.

---

## How it works and what happens to your data

```
You ──► Claude Desktop ──► this connector (runs on your PC) ──► TallyPrime at localhost:9000
                ▲                                                      │
                └────────── short summary of the figures ◄─────────────┘
```

- The connector starts automatically inside Claude Desktop and talks to Tally's built-in XML interface on **your own PC**.
- **The developer receives nothing.** No servers, accounts, analytics or tracking.
- **On your PC:** an optional audit log of write attempts. Nothing else is stored.
- **Sent to Anthropic:** the figures the connector returns become part of your Claude chat, like anything else you type. See [PRIVACY.md](PRIVACY.md).

### How figures are worked out

Trial balance, P&L, balance sheet, GST summary, ledger balances and statements are calculated by the connector from the vouchers in your books, for exactly the dates you ask. Tally is only asked for whole financial years (1 April to 31 March). This avoids two problems seen on real TallyPrime: report dates being ignored in Educational Mode, and Tally keeping the period from an earlier request. As a safety check, every ledger's total is compared with Tally's own year-end balance, and any difference is reported in the result.

---

## Limitations (v1)

- Windows only. TallyPrime must be **open with the company loaded**.
- Works in **Claude Desktop** only, not claude.ai in the browser or the mobile app.
- **One company at a time.** Switch companies in Tally (or set the company name in settings).
- Outstanding bills need **bill-wise details** enabled on party ledgers.
- GST summary is from ledger totals; it doesn't read invoice-level GST details or file returns.
- Ledger statements and the day book are limited to about 13 months and 12 months per request respectively.
- Report figures are worked out from your vouchers, so the connector reads every voucher of the financial year on each report. Very large companies may need a longer timeout in settings.
- Ledger names containing a double quote (`"`) aren't supported yet.
- In the Day Book, a Journal's "party" shows its first ledger; Journals have no party.
- **Educational Mode** TallyPrime only accepts entries dated the 1st, 2nd or 31st of a month; the voucher preview checks with Tally and stops such a date before you try to save it. It also stops dates before the company's books begin. Tally also ignores **report** dates that aren't the 1st, 2nd or 31st. Ledger, trial balance, P&L, balance sheet and GST figures are not affected (see *How figures are worked out*). Outstanding bills and stock values come straight from Tally for the date asked; if Tally used a different date, the result says so. If Tally used a later date, `overdue_days` is moved back to the date asked for; if it used an earlier one, bills dated after it are missing and `overdue_days` may be `null`.

---

## Troubleshooting

| What you see | What to do |
|---|---|
| "Can't reach TallyPrime at localhost:9000" | Open TallyPrime, load a company, and check **F1 → Settings → Connectivity** (Both/Server, port 9000). Make sure the port in the extension settings matches. |
| "No company is open" | Load a company in Tally (Alt+F3 / Select Company). |
| "Couldn't find the company named in settings" | Clear **Company name** in the extension settings, or type the exact name as shown in Tally. |
| Tally is slow or "did not answer within 30 seconds" | Ask for a shorter period, close any popup in Tally, or raise the timeout in settings. |
| Outstanding shows nothing | Enable **Maintain balances bill-by-bill** on the party ledgers in Tally. |
| "Ledger doesn't exist" | Ask Claude to search ledgers first; names must match Tally exactly. |
| A result says Tally gave figures "as on" a different date (Educational Mode) | Ask for bills or stock as on the 1st, 2nd or 31st of a month. Licensed TallyPrime doesn't have this restriction. |
| A result says vouchers "don't add up to Tally's own balance" | The connector cross-checks its figures against Tally's own year-end balance for every ledger. Check the named ledgers in Tally and please open an issue. |
| Voucher rejected because of the date | In Educational Mode use the 1st, 2nd or 31st of a month; otherwise check the date is inside the company's financial year. |
| Claude says writing is switched off | That's the default. Turn on **Allow writing to Tally** in the extension settings (take a backup first). |
| Windows Firewall prompt | Tally's port only needs to be reachable from this PC. Choose **Private networks** only, never Public. |

Still stuck? [Open an issue](https://github.com/suhrith13/tallyprime-claude-connector/issues) with the exact message (remove any client names or figures first).

---

## Verification status

| Area | Status |
|---|---|
| All 11 read and preview tools | ✅ Tested on real TallyPrime 7.2 (Educational Mode), v1.0.5 |
| Saving a voucher from Claude | ✅ Tested on real TallyPrime, v1.0.5: saved, showed in Day Book and ledger, trial balance still balanced, logged, duplicate blocked |
| Voucher preview checks | ✅ Tested on real TallyPrime: wrong ledger, unbalanced entry, wrong GST amount, wrong voucher type, date before books begin, Educational Mode date |
| Automated tests | ✅ 41 end-to-end checks against a simulated Tally (`mock/`) that copies the Educational Mode date behaviour seen on real Tally |
| Licensed (non-Educational) TallyPrime | ⏳ Not yet tested on a real licensed copy (simulated only) |
| Stock summary with real inventory | ⏳ Not yet tested (Test Company has no stock items) |
| Large companies (thousands of vouchers) | ⏳ Not yet tested |

Please report your TallyPrime version and results in an issue. Until more real-world reports come in, double-check important figures in Tally.

### Bugs found during testing

Real-Tally testing found these problems. All are fixed in 1.0.5. Details are in the [CHANGELOG](CHANGELOG.md).

| Found in | Problem | Fixed in |
|---|---|---|
| 1.0.0 | Balance sheet off by ₹2,20,000: the current year's profit was counted twice | 1.0.1 |
| 1.0.0 | Educational Mode rejected a 30 April voucher with an unclear error | 1.0.1 |
| 1.0.0 | Day Book could include vouchers outside the dates asked for | 1.0.1 |
| 1.0.1 | Day Book and ledger statements **silently dropped vouchers** on some date ranges | 1.0.2 / 1.0.3 |
| 1.0.1 | Day Book showed a purchase's ledger line (₹80,000) instead of the invoice total (₹94,400) | 1.0.2 |
| 1.0.1 | Voucher preview dropped a misspelt line, so an unbalanced entry and a wrong GST amount weren't flagged | 1.0.2 / 1.0.3 |
| 1.0.2 | Reports for a single month (e.g. October) returned **zero activity** | 1.0.3 |
| 1.0.2 | Mid-year opening balances wrong; trial balance and ledger search missed recent vouchers | 1.0.3 |
| 1.0.2 | Day Book limited to 93 days per request | 1.0.3 |
| 1.0.3 | `overdue_days` counted to Tally's substituted date (212 days instead of 74) | 1.0.4 |
| 1.0.4 | Voucher preview allowed a date before the books begin, and dates Educational Mode refuses | 1.0.5 |

**The root cause of most of these:** TallyPrime's Educational Mode accepts only the 1st, 2nd and 31st of a month. For report requests on other dates it silently keeps the period from the *previous* request, so results depended on which report ran before. Since 1.0.3 the connector asks Tally only for whole financial years and works out every period itself.

---

## For developers

```bash
npm install
npm run build          # bundles src/ into server/index.js
npm test               # end-to-end tests: MCP client -> connector -> mock Tally
npm run mock           # run the mock Tally on port 9000 (EDUCATIONAL=0 for licensed behaviour)
npm run pack           # build + create dist/tallyprime-connector.mcpb
```

- `src/tally/client.ts`: HTTP/XML transport (UTF-16, timeouts, one request at a time, Tally's hidden errors)
- `src/tally/xml.ts`: builds TDL collection exports (including voucher ledger lines) and parses the rows
- `src/tally/queries.ts`: what is asked of Tally, and period balances worked out from vouchers
- `src/tools/read.ts`, `src/tools/write.ts`: MCP tools
- `mock/`: simulated TallyPrime with the Test Company used for real-Tally testing. **Passing against the mock does not prove a TDL expression works on real Tally**; test new queries on a real TallyPrime (Educational Mode is free and enough).

Tally's XML conventions (UTF-16 bodies, normalised debit/credit signs, `Bill` collection fields) were cross-checked against the MIT-licensed [dhananjay1405/tally-mcp-server](https://github.com/dhananjay1405/tally-mcp-server).

## License

MIT. See [LICENSE](LICENSE). Provided "as is", without warranty of any kind. You are responsible for your books.