Tally Prime MCP Server

Note: Git history was rewritten on 16 Apr 2026 to remove accidentally committed auth tokens. All leaked credentials have been rotated. Thanks to @Journeyman1987 for flagging this.

An MCP (Model Context Protocol) server that bridges Tally Prime ERP with AI assistants like Claude, ChatGPT, GitHub Copilot, and any MCP-compatible client. Query financial reports, manage masters, create vouchers, and analyse GST data — all through natural language.

Features

• 29 MCP tools — financial reports, master data, stock, GST, voucher creation, plus dedicated company-management tools (load-company, set-active-company, list-loaded-companies, list-available-companies)

• Cold-load with credentials — load a password-protected company from a Tally with nothing resident, end-to-end via MCP. Edition-aware (Silver swaps, Gold accumulates). Documented in Editions.

• Companion GUI agent — runs in the user session, bridges Windows Session 0 isolation so the Session-0 service can spawn tally.exe and keystroke through credential prompts. Self-restarts on script update; version handshake refuses stale agents.

• DuckDB in-memory analytics — cached report tables for complex SQL queries

• OAuth 2.1 + PKCE authentication for remote/cloud deployments

• Security hardened — Helmet, CORS, rate limiting, audit logging, read-only mode

• Local & remote — run as a local stdio server or a cloud HTTP server behind a reverse proxy

• Windows installer (#18) — double-click .exe from "nothing installed" to "service running" in under 5 minutes. Bundles portable Node + NSSM; no admin pre-reqs beyond UAC.

• Status tray icon (#20) — at-a-glance health for non-developer operators. Service + agent + Tally + public URL all visible in one click.

Related MCP server: TallyPrime MCP Server

Prerequisites

• Tally Prime (Silver / Gold) with XML Server enabled

• Node.js 20+

Enable the XML server in Tally: F1 → Settings → Connectivity → Client/Server Configuration

TallyPrime acts as = Server
Port = 9000

Note: Avoid the Educational edition — its date-range limitations produce incomplete data.

Installation

Option A — Windows installer (recommended for client deployments)

A double-click TallyMCP-Setup-<version>.exe takes a Windows box from "nothing installed" to "service running" in under 5 minutes. Bundles portable Node.js + NSSM, prompts for the few values it can't auto-detect, registers the Windows service and the GUI agent at-logon task. See docs/installer.md for build instructions.

Option B — From source (development / custom deployments)

git clone https://github.com/JINA-CODE-SYSTEMS/tally-mcp-server.git
cd tally-mcp-server
npm install
npx tsc

Configuration

Copy .env.example to .env and configure:

Editions

Tally Prime ships in two relevant editions, and load-company adapts its behavior to each. You must set TALLY_EDITION correctly — defaulting to silver is the safe assumption.

Why this matters for the multi-subsidiary cross-reference workflow: Silver clients can only query one company at a time, so an LLM doing "compare ledgers across 3 subsidiaries" will pay the ~10–30s restart latency between each. Gold clients can pre-load all subsidiaries and switch between them for free.

Why no auto-detection: Tally's edition isn't reliably exposed via the XML server. Rather than ship a fragile auto-detect that could miscategorize and silently degrade behavior, the server takes the configured value as authoritative.

Background: why Tally must be restarted to load a company

Tally Prime has no XML or TDL primitive that loads a company from disk into memory. We confirmed this by reverse-engineering every dispatch surface the XML server exposes (see notes/tdl-experiments.md). The built-in $$CmpLoadCompany is misleadingly named — it's "select among already-loaded companies", not "load from disk". Loading is exclusively initiated by Tally process startup (via Load= directives in tally.ini) or the Tally UI (Alt+F3).

Therefore load-company works the only way it can: rewrites tally.ini, kills tally.exe, and asks the GUI agent (which lives in the user's interactive desktop session) to start it again. This is unavoidable until Tally exposes a load verb in a future protocol version.

Operational requirement: GUI agent must be running

Because the MCP server typically runs as a Windows service in Session 0 (no desktop), it cannot spawn tally.exe directly. The companion script scripts/tally-gui-agent-v2.ps1 runs in the user's interactive session and acts as the bridge — load-company IPCs to it to perform the spawn.

• Install the agent to start at user logon. setup-windows.ps1 registers a TallyMCPAgent Scheduled Task at-logon for the configured user — no manual setup needed. The Windows installer (option A above) does the same automatically.

• Self-update on deploy. When a git pull replaces tally-gui-agent-v2.ps1 on disk, the running agent detects the mtime change between commands and re-launches into the new version. Combined with the at-logon task, deploys propagate without operator intervention.

• Version handshake. The agent reports agentVersion on every response. load-company refuses to call destructive actions on an agent older than REQUIRED_AGENT_VERSION and returns a clear remediation message instead of silently no-op'ing on unrecognized IPC fields. open-company-debug surfaces both the running version and versionOk status.

• No LLM key required for the deterministic actions (ping, start-tally, select-and-unlock-company). Only set ANTHROPIC_API_KEY / OPENAI_API_KEY if you want the LLM-guided UI navigation fallback (open-company Strategy 3).

• load-company pings the agent before doing anything destructive — if the agent isn't responding (or is too old), the tool refuses to kill Tally and returns a clear error. So a misconfigured deployment never ends up worse than it started.

• Check liveness any time via open-company-debug — it returns guiAgentResponding, guiAgentVersion, guiAgentVersionOk, and guiAgentVersionRequired.

Setup

Local (Claude Desktop)

Add to your claude_desktop_config.json (File → Settings → Developer):

{
  "mcpServers": {
    "Tally Prime": {
      "command": "node",
      "args": ["<path-to-repo>/dist/index.mjs"]
    }
  }
}

Local (VS Code / GitHub Copilot)

Add to your workspace .vscode/mcp.json:

{
  "servers": {
    "tally-prime": {
      "type": "stdio",
      "command": "node",
      "args": ["<path-to-repo>/dist/index.mjs"]
    }
  }
}

Remote / Cloud

For browser-based clients (ChatGPT, Claude web, Copilot) that can't reach a local Tally install, deploy the server on a machine that can access Tally and expose it over HTTPS.

{
  "servers": {
    "tally-prime": {
      "type": "http",
      "url": "https://your-domain.example/mcp"
    }
  }
}

The server uses OAuth 2.1 with PKCE for authentication. Detailed setup guides:

• Linux-based Server (recommended — Tally connects via SSH tunnel)

• Windows Server

Available Tools

Company Management

Optional credential-hint config (used by list-available-companies): drop a .tally-mcp-companies.json into the Tally data path (or set TALLY_COMPANIES_CONFIG to point elsewhere) with the shape:

{
  "100000": { "requiresCredentials": true,  "knownUsername": "admin", "notes": "Edit Log; user-based security" },
  "200000": { "requiresCredentials": false, "notes": "Auto-loads cleanly" }
}

The config never stores passwords — only the hint that one is needed, so callers can prompt the human up-front instead of waiting for load-company to fail.

Financial Reports

Inventory

GST

Master Data

Write Operations

Write tools are disabled when READONLY_MODE=true.

Analytics

Most report tools cache their output in a temporary DuckDB table (returned as tableID). Use query-database to run analytical SQL — aggregate, filter, join, sort — on those cached tables. Tables auto-expire after 15 minutes (configurable via DB_TABLE_RETENTION_MS).

Security

• OAuth 2.1 + PKCE with constant-time token comparison

• Helmet security headers

• CORS restricted to configured origins

• Rate limiting on authentication endpoints (configurable via AUTH_RATE_LIMIT_*)

• SQL validation — only SELECT statements allowed in query-database

• Audit logging — every tool invocation logged with timestamp, args (secrets redacted), and duration

• Read-only mode — disable all write operations via env var

Architecture

┌─────────────┐     ┌──────────────────────┐     ┌─────────────┐
│  MCP Client │────▶│   Tally MCP Server   │────▶│ Tally Prime │
│  (Claude,   │ MCP │  Express + MCP SDK   │ XML │  Port 9000  │
│  Copilot…)  │◀────│  DuckDB · OAuth 2.1  │◀────│             │
└─────────────┘     └──────────────────────┘     └─────────────┘

Scripts & Utilities

The scripts/ directory contains Windows-specific automation tools used by the open-company feature and server deployment.

GUI Agent — Companion Script for Cross-Session Operations

powershell -ExecutionPolicy Bypass -File scripts\tally-gui-agent-v2.ps1 [-LLMProvider anthropic|openai] [-MaxSteps 15]

Runs in the interactive desktop session where Tally is visible. The MCP server (which typically runs in Windows Session 0 with no desktop) communicates with this agent via JSON file IPC to perform actions that need a real desktop — most importantly launching tally.exe for load-company and automating Alt+F3 → Select Company for the optional LLM-guided fallback.

• Install: Add to Windows Startup folder or Task Scheduler (run at user logon)

• Requires TallyUI.dll (see below)

• LLM key is OPTIONAL. Deterministic actions (ping, start-tally) work without one. Set ANTHROPIC_API_KEY or OPENAI_API_KEY only if you need the LLM-guided UI navigation fallback (open-company Strategy 3).

• LLM model, tokens, and timeout are configurable via env vars (see Configuration)

TallyUI.dll — Win32 Interop Library

C:\Windows\Microsoft.NET\Framework64\v4.0.30319\csc.exe /target:library /reference:System.Drawing.dll /out:scripts\TallyUI.dll scripts\TallyUI.cs

Compiled C# library wrapping Windows APIs for window management, keystroke injection, and screenshot capture. Required by GUI Agent v2. The setup-windows.ps1 script compiles this automatically.

Windows Service Setup

powershell -ExecutionPolicy Bypass -File scripts\setup-windows.ps1 [-InstallDir C:\tally-mcp-server] [-NodePath "..."] [-ServiceName TallyMCP]

One-time setup to register the MCP server as a Windows service via NSSM. Configures auto-start, log rotation, loads .env variables, and registers two at-logon scheduled tasks: TallyMCPAgent (the GUI agent) and TallyMCPTray (the status tray icon). See Windows Server Setup for the full guide.

Status Tray Icon (issue #20)

powershell -ExecutionPolicy Bypass -WindowStyle Hidden -File scripts\tray\tally-mcp-tray.ps1

Runs in the user's interactive desktop session and surfaces a coloured tray icon (green/yellow/red/gray) reflecting overall TallyMCP health. Polls every few seconds for: service status, GUI agent task + process, Tally Prime process, and a public-URL OAuth metadata probe. Right-click for one-click admin actions:

• Open logs folder (also: double-click the tray icon)

• Restart service (prompts UAC for admin)

• Restart GUI agent

• Launch Tally Prime (uses TALLY_EXE_PATH from .env)

• Reconfigure... (re-runs firstrun-config.ps1 for .env changes)

• Quit (hide tray) — hides the icon only; service and agent keep running

setup-windows.ps1 registers this as TallyMCPTray ONLOGON; the Windows installer (Option A above) does the same. Pass -SkipTrayTask to either if you don't want the tray icon (e.g. headless server install).

No new runtime dependencies — uses WinForms NotifyIcon + System.Drawing already present on every Windows 10+ box.

Deploy a New Version

After pushing changes to origin/main, refresh the running service on the Windows box.

One command (recommended):

# From an admin PowerShell on the Tally box
cd C:\tally-mcp-server
.\scripts\deploy.ps1

The script halts on any failure rather than leaving a half-deployed state. It runs:

1. git pull origin main

2. npm install (skip with -SkipInstall when package.json hasn't changed)

3. npm run build

4. Force-stops the service (kills the node.exe process — graceful stop is unreliable under NSSM on Windows), then Start-Service TallyMCP and verifies the service is Running afterwards

Useful flags:

Smoke test after deploy (from anywhere):

curl -sS https://<your-domain>/.well-known/oauth-protected-resource

A JSON body with resource confirms the server is up. A 502 means the upstream Node process didn't come back — tail logs\service-*.log for the cause (most often a missing env var or a port collision).

Manual fallback — if deploy.ps1 ever misbehaves, the equivalent five-step recipe is:

cd C:\tally-mcp-server
git pull origin main
npm install
npm run build
Restart-Service TallyMCP
Get-Service TallyMCP

Development

npm run build          # Compile TypeScript
npm test               # Build + run tests
npx tsc --noEmit       # Type-check without emitting
npm audit              # Check for dependency vulnerabilities

Credits

Originally created by Dhananjay Gokhale. This fork is maintained by Jinacode Systems.

License

AGPL-3.0-or-later