Content
<p align="center">
<img src="assets/icon.png" alt="Tally MCP Server" width="180">
</p>
# Tally MCP Server
A Model Context Protocol (MCP) server that lets Claude read from and write to
[TallyPrime](https://tallysolutions.com) via its built-in XML/HTTP gateway.
## How it works
```
Claude Desktop <--stdio--> ┐
├─ this MCP server <--HTTP/XML--> TallyPrime (localhost:9000)
Remote MCP client <--HTTP--> ┘
```
Locally, Claude Desktop launches this server as a stdio process. Remotely, it
can also run as an HTTP server. Either way, tool calls get translated into
Tally's XML request format, sent to Tally's HTTP gateway, and returned as
cleaned-up JSON. There's also an optional local SQL cache (PGLite) for
ad-hoc queries beyond the fixed report tools.
## Prerequisites
- [Node.js](https://nodejs.org) 18+
- TallyPrime installed, running, with a company open
- Tally's HTTP gateway enabled:
`F1 (Help) > Settings > Connectivity > Client/Server configuration` and set
**TallyPrime acts as** to `Both` or `Server`, port `9000` (default).
## Setup
```bash
npm install
npm run build
```
## Configure Claude Desktop
**Option A — Extension (recommended):** package as a `.dxt` and install
with one click. See [docs/EXTENSION_PACKAGING.md](docs/EXTENSION_PACKAGING.md).
**Option B — manual config:** edit your Claude Desktop config file:
- Windows: `%APPDATA%\Claude\claude_desktop_config.json`
- macOS: `~/Library/Application Support/Claude/claude_desktop_config.json`
Add:
```json
{
"mcpServers": {
"tally": {
"command": "node",
"args": ["D:\\Projects\\Tally-MCP-Server\\dist\\index.js"],
"env": {
"TALLY_URL": "http://localhost:9000"
}
}
}
}
```
Restart Claude Desktop. You should see a hammer/tools icon indicating the
`tally` server is connected.
## Available tools
17 tools total — read (ledgers, stock, groups, voucher types, cost centres,
day book, ledger vouchers, company info, P&L, balance sheet, trial balance,
stock summary, bills receivable/payable), write (create ledger, group,
stock item, voucher), and SQL cache (`sync_to_sql`, `query_sql`). Full
reference with args: **[docs/TOOLS.md](docs/TOOLS.md)**.
Dates use `DD-MM-YYYY` format, matching Tally's convention.
## Running remotely (HTTP)
```bash
TALLY_MCP_TOKEN=<secret> npm run start:http
```
See [docs/HTTP_DEPLOYMENT.md](docs/HTTP_DEPLOYMENT.md).
## Docs
- [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md) — request flow, file responsibilities
- [docs/TALLY_XML_GUIDE.md](docs/TALLY_XML_GUIDE.md) — how Tally's XML gateway works, gotchas
- [docs/TOOLS.md](docs/TOOLS.md) — full tool reference + how to add a new tool
- [docs/SQL_CACHE.md](docs/SQL_CACHE.md) — the PGLite SQL cache, schema, examples
- [docs/HTTP_DEPLOYMENT.md](docs/HTTP_DEPLOYMENT.md) — running as a remote HTTP server
- [docs/EXTENSION_PACKAGING.md](docs/EXTENSION_PACKAGING.md) — packaging as a `.dxt` Claude Desktop Extension
## Project structure
```
src/
tally.ts Tally HTTP client: sends XML, handles connection/timeout errors
clean.ts Normalizes Tally's raw XML->JSON into predictable JSON
templates.ts Renders the Nunjucks XML templates in templates/
db.ts PGLite SQL cache: sync_to_sql / query_sql
tools.ts MCP tool definitions + XML request builders
server.ts Shared MCP Server construction (used by both entry points)
index.ts stdio entry point (local Claude Desktop)
http-server.ts HTTP entry point (remote clients)
templates/
*.xml.njk Nunjucks templates for each Tally XML request shape
manifest.json Claude Desktop Extension (.dxt) manifest
```
## Environment variables
| Variable | Default | Purpose |
|---|---|---|
| `TALLY_URL` | `http://localhost:9000` | Tally's HTTP gateway address |
| `PORT` | `3939` | Port for `npm run start:http` |
| `TALLY_MCP_TOKEN` | _(unset)_ | Bearer token required on the HTTP server's `/mcp` endpoint if set |
## Troubleshooting
- **"Could not reach TallyPrime"** — Tally isn't running, or the HTTP gateway
isn't enabled on port 9000.
- **"Tally returned an empty response"** — Tally is running but no company is
open.
- **`create_ledger` / `create_voucher` fails with errors** — check that the
parent group / ledger names exactly match what exists in Tally (names are
case-sensitive and must match exactly).
## Roadmap / not yet supported
- Editing or deleting existing vouchers/ledgers/masters
- Inventory vouchers (Stock Journal, Manufacturing Journal, etc.)
- GST-specific reports (GSTR-1, GSTR-3B)
- Multi-company support (currently always targets whichever company is open)
