Bharat MCP

bharat-mcp 🇮🇳

一个 MCP 服务，帮助 Claude（以及任何兼容 MCP 的 AI）了解印度的金融和文书流程。

让你的 AI 创建 GST 发票、检查 GSTIN、解释银行对账单中的薪资去向、解读 UPI 摘要，或根据 IFSC 查找银行网点。它在你的电脑上运行，你的对账单不会离开本地。

“为我在 Bengaluru 的工作室开一张 GST 发票，收件方是 Mumbai 的 Acme Media，内容为 10 小时视频剪辑，费率为每小时 ₹1,500。”

→ Claude 会判断这是跨邦交易（IGST 18%），并生成 Invoice_INV_2026-27_001.pdf，其中包含 HSN/SAC、供应地点和金额大写。

“分析 ~/Downloads/HDFC_statement.pdf。我的钱都花到哪里了？我应该取消哪些订阅？”

→ 按类别统计支出（Swiggy/Zomato、Blinkit/Zepto、房租、EMI、SIP 等）、每月现金流、主要收款方和定期付款。

工具

工具	功能	网络
create_gst_invoice	GST 税务发票 PDF（Rule 46 字段、CGST/SGST/UTGST/IGST、附加税、舍入调整、银行和 UPI 详情）	离线
calculate_gst	任意明细项的税额拆分：邦内或跨邦交易、含 GST 价格、附加税	离线
validate_gstin	检查格式、邦代码和校验和；解码 PAN 和实体类型	离线
find_gst_rate	根据 HSN 编码或商品名称查询商品的 GST 税率，数据来自《印度公报》税率通知并应用所有修订；显示每条匹配结果及其通知和序号	离线
search_hsn_sac	根据日常描述（“笔记本电脑”“酥油”“CA 服务”）或编码前缀，查找 HSN（商品）或 SAC（服务）编码；数据来自 GST 门户的官方列表	离线
lookup_hsn_sac	检查编码是否存在，并显示其章节、品目和子编码；输入错误时推荐最接近的有效编码	离线
amount_in_words	将 ₹ 金额转换为英文大写，采用 lakh/crore 单位（“Rupees One Lakh Twenty Thousand Only”）	离线
analyze_bank_statement	根据 PDF 或 CSV 对账单，按类别统计支出、每月收支、主要收款方、定期付款和 UPI 使用情况	离线
convert_bank_statement	将 PDF 对账单转换为适用于 Excel/Sheets 的整洁 CSV，包含类别、收款方和解码后的 UPI 详情	离线
parse_upi_narration	将 SBI、HDFC、ICICI、Axis、Kotak 等银行的 UPI 摘要解码为收款方、VPA、应用、RRN 和交易方向	离线
lookup_ifsc	查询银行、网点、地址、MICR 以及是否支持 UPI/IMPS/NEFT/RTGS	Razorpay IFSC API
lookup_pincode	查询 PIN 编码对应的区、邦和邮局	India Post 数据

此外还包含一个提示词 monthly_money_review，可将对账单转换为摘要和储蓄计划。

安装

需要 Node.js 22.13 或更高版本。

Claude Code

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

Claude Desktop：将以下内容添加到 claude_desktop_config.json（Settings → Developer → Edit Config）：

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

从源代码安装

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

配置（可选）

环境变量	默认值	用途
BHARAT_MCP_OUTPUT_DIR	~/bharat-mcp/invoices	发票 PDF 的保存位置
BHARAT_MCP_IFSC_API	https://ifsc.razorpay.com	如有需要，可自托管 IFSC API
BHARAT_MCP_PINCODE_API	https://api.postalpincode.in	PIN 编码 API 基础 URL

银行对账单

只需指定银行发给你的 PDF（或网上银行导出的 CSV）。

• **版式：**自动检测表格，无论标题如何表述（“Withdrawal Amt.” / “Debit” / “Withdrawal (Dr)/ Deposit (Cr)” / “DR/CR”……）。支持分两行的标题、显示在行上方或下方的换行摘要、日期从新到旧排列的对账单，以及多页对账单。已针对 SBI、HDFC、ICICI、Axis 和 Kotak 风格的版式进行测试。
• **受密码保护的 PDF：**Claude 会向你询问密码。密码仅用于打开文件，绝不会被存储。
• **与余额核对：**每一行都会与滚动余额进行核对。若借方或贷方被误读，会自动修正；若缺少行，则会报告其日期，让你知道是否可以信任这些数字。
• 扫描版对账单（照片，没有文本层）无法解析。Claude 可以自行读取这些对账单并传入各行数据。

如果无法解析你银行的 PDF，请运行 convert_bank_statement 并设置 debug: true。你会得到一份布局预览，其中每个字母和数字都经过遮盖，可以安全地粘贴到 GitHub issue 中。

HSN/SAC 编码

编码和说明来自 GST 门户网站的官方主清单（HSN_SAC.xlsx）：包含 21,928 个 HSN 编码和 681 个 SAC 编码。数据已打包，因此可以离线搜索。create_gst_invoice 还会在某个项目的 HSN/SAC 编码不在清单中时发出警告。

• 说明内容与发布时完全一致。仅清理了电子表格残留问题，并合并了表格中重复列出的七个编码；这些更改记录在 data/hsn_sac.json 中，同时记录了源文件的 SHA-256 和下载日期。
• 日常用语（“atta”、“AC”、“laptop”、“CA”）会映射到关税表述，但每个结果都是官方编码。
• GST 税率来自 find_gst_rate（见下文）。
• 分类由你负责。如有不确定之处，请向你的 CA 确认。

要更新清单：下载最新的 HSN_SAC.xlsx，然后运行 pip install openpyxl 和 npm run update-hsn -- path/to/HSN_SAC.xlsx。

GST 税率

find_gst_rate 使用的税率通知与 印度政府公报中发布的内容完全一致：

通知	公报 ID	生效日期	内容
09/2025-Central Tax (Rate)	CG-DL-E-17092025-266209	22 Sep 2025	商品税率附表 I–VII（5%、18%、40%、3%、0.25%、1.5%、28%）
10/2025-Central Tax (Rate)	CG-DL-E-17092025-266210	22 Sep 2025	免税（零税率）商品
19/2025-Central Tax (Rate)	CG-DL-E-31122025-268978	1 Feb 2026	烟草和 pan masala 税率调至 40%，biris 调至 18%；删除 28% 附表
01/2026-Central Tax (Rate)	CG-DL-E-01052026-272190	1 May 2026	更新饮料税则编码
02/2026 and 03/2026-Central Tax (Rate)	CG-DL-E-27102026-277454	1 Nov 2026	第 57 届 GST 委员会：翻新拖拉机轮胎税率为 5%，生物刺激剂和车前子种子免税

数据核查方式：

• CGST（09/2025-CT）和 IGST（09/2025-IT）通知会分别解析，且每条内容都必须一致，其中 IGST = 2 × CGST。
• 附表中的每个 HSN 编码都必须存在于官方 HSN 列表中。
• 每项修订都会录入 scripts/gst_amendments.json，且除非修订内容出现在修订通知的 PDF 中，否则构建会失败。
• Gazette PDF 存放在 sources/gazette/ 中，并附有 SHA-256 哈希值。运行 npm run update-rates 以重新构建。

须知：

• 同一个编码可能对应多个不同税率的条目。 适用的条目取决于具体描述，例如“预包装并贴有标签”或“除……以外”。工具会显示所有匹配条目，而不会自行猜测。
• 目前尚未涵盖服务（SAC 编码）。 相关税率分散在第 11/2017 号通知及多项修订中。
• 自 2026 年 2 月 1 日起，补偿附加税为零。
• 数据截至 source.in_force_as_of 中的日期。 新的 GST 委员会会议结束后，请查阅 Gazette 中的新税率通知，并将其添加到 scripts/gst_amendments.json。
• 如果某项商品的税率与其 HSN 编码对应的所有已通知税率都不匹配，create_gst_invoice 会发出警告。

隐私

• 银行对账单解析与分析、GST 计算和发票生成均完全在你的设备上运行。
• 只有 lookup_ifsc 和 lookup_pincode 会发起网络请求，且只会发送你查询的编码。
• 除了你要求生成的发票 PDF 外，不会记录或存储任何内容。

注意事项

• validate_gstin 会检查结构和校验和，但不会确认 GST 门户上的注册是否有效。
• GST 税率会变化，因此请始终传入适用于商品的税率。
• 自动分类只是尽可能准确的估算，适合个人概览，但不能作为会计建议。

开发

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

非常欢迎贡献，尤其是新的银行交易描述格式（在 test/ 中添加样本）、src/upi.ts 中的商户关键词，以及新工具（请参阅路线图）。

发布（维护者）

每次推送和拉取请求都会在 Ubuntu 和 Windows 上使用 Node 22 和 24 运行测试（.github/workflows/ci.yml）。

发布 GitHub Release 时会自动发布（.github/workflows/release.yml）。工作流会：

1. 检查标签、package.json 和 server.json 是否一致；
2. 运行测试；
3. 验证 server.json；
4. 使用 Trusted Publishing 发布到 npm（无需令牌；会自动添加来源证明）；
5. 使用 GitHub OIDC 发布到 MCP Registry。

要发布新版本：

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

然后在 GitHub 上：依次选择 Releases → Draft a new release，选择新标签（例如 v0.4.1），然后点击 Publish release。

在 npmjs.com 上进行一次性设置：在软件包的 Settings → Trusted publishing 中，添加 GitHub Actions，填写用户 nansa1、仓库 bharat-mcp、工作流 release.yml，并在 Allowed actions 下勾选 npm publish。

路线图

• 电子发票 JSON（IRN 架构）和电子运单辅助工具
• HSN/SAC 编码搜索（v0.3）
• 《印度公报》中的商品 GST 税率（v0.4）
• 服务 GST 税率（SAC）
• 印度所得税计算器（旧税制与新税制）
• PDF 对账单解析（v0.2）
• 信用卡对账单
• 通过可插拔的提供方查询列车 PNR 和运行状态（需要 API 密钥）
• 印地语和地区语言输出

许可证

MIT