Back to Browse

Bharat MCP Server

by Nansa1
Developer ToolsLow Risk10.0MCP RegistryLocal
Free

Server data from the Official MCP Registry

India tools: GST invoices and official GST rates, HSN/SAC search, UPI and bank statement analysis

About

India tools: GST invoices and official GST rates, HSN/SAC search, UPI and bank statement analysis

Security Report

10.0
Low Risk10.0Low Risk

Valid MCP server (2 strong, 3 medium validity signals). No known CVEs in dependencies. Package registry verified. Imported from the Official MCP Registry.

4 files analyzed · 1 issue found

Security scores are indicators to help you make informed decisions, not guarantees. Always review permissions before connecting any MCP server.

Permissions Required

This plugin requests these system permissions. Most are normal for its category.

file_system

Check that this permission is expected for this type of plugin.

What You'll Need

Set these up before or after installing:

Folder where invoice PDFs are saved (default: ~/bharat-mcp/invoices)Optional

Environment variable: BHARAT_MCP_OUTPUT_DIR

How to Install

Add this to your MCP configuration file:

{
  "mcpServers": {
    "bharat-mcp": {
      "command": "npx",
      "args": [
        "-y",
        "@adnansaliyawala/bharat-mcp@0.4.1"
      ],
      "env": {
        "BHARAT_MCP_OUTPUT_DIR": "your-bharat-mcp-output-dir-here"
      }
    }
  }
}

Some servers take additional arguments. See the repository for details.

Documentation

View on GitHub

From the project's GitHub README.

bharat-mcp 🇮🇳

An MCP server that teaches Claude (and any MCP-compatible AI) how India's money and paperwork work.

Ask your AI to make a GST invoice, check a GSTIN, explain where your salary went from a bank statement, decode a UPI narration, or find a bank branch from an IFSC. It runs on your computer, and your statements never leave it.

"Make a GST invoice from my studio in Bengaluru to Acme Media in Mumbai for 10 hours of video editing at ₹1,500/hr."

→ Claude works out that this is inter-state (IGST 18%) and writes Invoice_INV_2026-27_001.pdf with HSN/SAC, place of supply and the amount in words.

"Analyse ~/Downloads/HDFC_statement.pdf. Where did my money go, and which subscriptions should I cancel?"

→ Spending by category (Swiggy/Zomato, Blinkit/Zepto, rent, EMIs, SIPs…), monthly cash flow, top payees and recurring payments.

Tools

ToolWhat it doesNetwork
create_gst_invoiceGST tax invoice PDF (Rule 46 fields, CGST/SGST/UTGST/IGST, cess, round-off, bank and UPI details)Offline
calculate_gstTax split for any line items: intra- vs inter-state, GST-inclusive prices, cessOffline
validate_gstinFormat, state code and checksum check; decodes PAN and entity typeOffline
find_gst_rateGST rate for goods by HSN code or product name, from the Gazette of India rate notifications with every amendment applied; shows each matching entry with its notification and serial numberOffline
search_hsn_sacFind HSN (goods) or SAC (services) codes by everyday description ("laptop", "ghee", "CA services") or code prefix, from the GST portal's official listOffline
lookup_hsn_sacCheck whether a code exists, with its chapter, heading and sub-codes; suggests the nearest valid code for a typoOffline
amount_in_words₹ to words in lakh/crore ("Rupees One Lakh Twenty Thousand Only")Offline
analyze_bank_statementCategorised spend, monthly in/out, top payees, recurring payments and UPI usage, from a PDF or CSV statementOffline
convert_bank_statementPDF statement → clean CSV for Excel/Sheets, with categories, payees and decoded UPI detailsOffline
parse_upi_narrationDecodes UPI narrations from SBI, HDFC, ICICI, Axis, Kotak and others into payee, VPA, app, RRN and directionOffline
lookup_ifscBank, branch, address, MICR and UPI/IMPS/NEFT/RTGS supportRazorpay IFSC API
lookup_pincodeDistrict, state and post offices for a PIN codeIndia Post data

It also includes a prompt, monthly_money_review, that turns a statement into a summary and a savings plan.

Install

Requires Node.js 22.13 or later.

Claude Code

claude mcp add bharat -- npx -y @adnansaliyawala/bharat-mcp

Claude Desktop: add this to claude_desktop_config.json (Settings → Developer → Edit Config):

{
  "mcpServers": {
    "bharat": { "command": "npx", "args": ["-y", "@adnansaliyawala/bharat-mcp"] }
  }
}

From source

git clone https://github.com/nansa1/bharat-mcp && cd bharat-mcp && npm install && npm run build
claude mcp add bharat -- node /absolute/path/to/bharat-mcp/dist/index.js

Configuration (optional)

Env varDefaultPurpose
BHARAT_MCP_OUTPUT_DIR~/bharat-mcp/invoicesWhere invoice PDFs are saved
BHARAT_MCP_IFSC_APIhttps://ifsc.razorpay.comSelf-host the IFSC API if you like
BHARAT_MCP_PINCODE_APIhttps://api.postalpincode.inPIN code API base URL

Bank statements

Just point it at the PDF your bank emails you (or a CSV export from net banking).

  • Layouts: detects the table automatically, whatever the header wording ("Withdrawal Amt." / "Debit" / "Withdrawal (Dr)/ Deposit (Cr)" / "DR/CR"…). Handles headers on two lines, narrations that wrap above or below the row, newest-first statements, and multi-page statements. It has been tested on SBI, HDFC, ICICI, Axis and Kotak style layouts.
  • Password-protected PDFs: Claude will ask you for the password. It is used only to open the file and is never stored.
  • Checked against the balance: every row is reconciled with the running balance. A misread debit/credit is fixed automatically, and a missing row is reported with its date, so you know whether to trust the numbers.
  • Scanned statements (photos, no text layer) can't be parsed. Claude can read those itself and pass the rows in.

If your bank's PDF doesn't parse, run convert_bank_statement with debug: true. You get a layout preview with every letter and digit masked, which is safe to paste into a GitHub issue.

HSN/SAC codes

Codes and descriptions come from the GST portal's official master list (HSN_SAC.xlsx): 21,928 HSN codes and 681 SAC codes. The data is bundled, so search works offline. create_gst_invoice also warns when an item's HSN/SAC code isn't in that list.

  • Descriptions are kept exactly as published. The only changes are cleaning spreadsheet artefacts and merging seven codes the sheet lists twice; these are recorded in data/hsn_sac.json, along with the source file's SHA-256 and download date.
  • Everyday names ("atta", "AC", "laptop", "CA") are mapped to tariff wording, but every result is an official code.
  • GST rates come from find_gst_rate (see below).
  • Classification is your responsibility. When it is unclear, confirm it with your CA.

To refresh the list: download the latest HSN_SAC.xlsx, then run pip install openpyxl and npm run update-hsn -- path/to/HSN_SAC.xlsx.

GST rates

find_gst_rate uses the rate notifications exactly as published in the Gazette of India:

NotificationGazette IDIn force fromWhat it does
09/2025-Central Tax (Rate)CG-DL-E-17092025-26620922 Sep 2025Rate schedules I–VII for goods (5%, 18%, 40%, 3%, 0.25%, 1.5%, 28%)
10/2025-Central Tax (Rate)CG-DL-E-17092025-26621022 Sep 2025Exempt (nil-rated) goods
19/2025-Central Tax (Rate)CG-DL-E-31122025-2689781 Feb 2026Tobacco and pan masala to 40%, biris to 18%; 28% schedule removed
01/2026-Central Tax (Rate)CG-DL-E-01052026-2721901 May 2026Beverage tariff codes updated
02/2026 and 03/2026-Central Tax (Rate)CG-DL-E-27102026-2774541 Nov 202657th GST Council: retreaded tractor tyres 5%, bio-stimulants, psyllium seeds exempt

How the data is checked:

  • The CGST (09/2025-CT) and IGST (09/2025-IT) notifications are parsed independently and must agree entry for entry, with IGST = 2 × CGST.
  • Every HSN code in the schedules must exist in the official HSN list.
  • Each amendment is transcribed in scripts/gst_amendments.json, and the build fails unless its text appears in the amending notification's PDF.
  • The Gazette PDFs are in sources/gazette/, with their SHA-256 hashes. Run npm run update-rates to rebuild.

Things to know:

  • One code can have several entries at different rates. The right one depends on the wording, for example "pre-packaged and labelled" or "other than …". The tool shows every matching entry instead of guessing.
  • Services (SAC codes) are not covered yet. Their rates are spread across Notification 11/2017 and many amendments.
  • Compensation cess is nil from 1 February 2026.
  • The data is current up to the date in source.in_force_as_of. After a new GST Council meeting, check the Gazette for new rate notifications and add them to scripts/gst_amendments.json.
  • create_gst_invoice warns when an item's rate doesn't match any rate notified for its HSN code.

Privacy

  • Statement parsing and analysis, GST maths and invoice generation run entirely on your machine.
  • Only lookup_ifsc and lookup_pincode make network calls, and they send only the code you look up.
  • Nothing is logged or stored apart from the invoice PDFs you ask for.

Caveats

  • validate_gstin checks structure and checksum. It does not confirm that a registration is active on the GST portal.
  • GST rates change, so always pass the rate that applies to your item.
  • Automatic categories are a best guess. They are good for a personal overview, but they are not accounting advice.

Development

npm install
npm test          # builds, then runs unit tests and an end-to-end MCP client test
npm run inspect   # opens the MCP Inspector

Contributions are very welcome, especially new bank narration formats (add a sample to test/), merchant keywords in src/upi.ts, and new tools (see the roadmap).

Releasing (maintainers)

Every push and pull request runs the tests on Ubuntu and Windows with Node 22 and 24 (.github/workflows/ci.yml).

Publishing is automatic when a GitHub release is published (.github/workflows/release.yml). The workflow:

  1. checks that the tag, package.json and server.json agree;
  2. runs the tests;
  3. validates server.json;
  4. publishes to npm with Trusted Publishing (no token; provenance is added automatically);
  5. publishes to the MCP Registry with GitHub OIDC.

To release a new version:

npm version patch          # or minor / major; also updates server.json, commits and tags
git push --follow-tags

Then on GitHub: Releases → Draft a new release, choose the new tag (e.g. v0.4.1), and click Publish release.

One-time setup on npmjs.com: in the package's Settings → Trusted publishing, add GitHub Actions with user nansa1, repository bharat-mcp, workflow release.yml, and tick npm publish under Allowed actions.

Roadmap

  • E-invoice JSON (IRN schema) and e-way bill helpers
  • HSN/SAC code search (v0.3)
  • GST rates for goods from the Gazette of India (v0.4)
  • GST rates for services (SAC)
  • Indian income-tax calculator (old vs new regime)
  • PDF statement parsing (v0.2)
  • Credit-card statements
  • Train PNR and running status, via a pluggable provider (needs an API key)
  • Hindi and regional-language output

License

MIT

M8ven Score

Reviews

No reviews yet

Be the first to review this server!