Skip to content
Back to search

banking-mcp-server

An MCP server, written in TypeScript, that lets an AI agent such as Claude Desktop use the Secure Banking API. The agent can check balances and read transaction history directly, and it can move…

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today

Check it deeper on your machine

It has changed since its scan on 19 Nov 2026.

As a Claude Code plugin, install it and then ask Claude Code:

/plugin marketplace add keithmackay/mackayi/plugin install scanskillsafety@mackayiDo a deep scan of https://github.com/heena5498/banking-mcp-server with scanskillsafety

Or from a terminal, clone it and run it:

git clone https://github.com/keithmackay/scanskillsafety-skill ~/.claude/skills/scanskillsafetynode ~/.claude/skills/scanskillsafety/cli.cjs --deep 'https://github.com/heena5498/banking-mcp-server'

It checks the exact commit: every file, its packages against OSV (api.osv.dev), how it compares with this page's scan (findsafeskills.com receives the repository's address), and, if you agree, Claude reading every file with your own Claude subscription. It never runs the code.

Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/heena5498--banking-mcp-server/badge.svg)](/listings/heena5498--banking-mcp-server)

HTML

<a href="/listings/heena5498--banking-mcp-server"><img src="/api/listings/heena5498--banking-mcp-server/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

Prerequisites

- Node.js 22+ - A running [Secure Banking API](https://github.com/heena5498/secure-banking-application) (Docker + Java 25). Not needed for the tests, which use a mock bank. - Claude Desktop, or any MCP client

Install, build and test

npm install
npm run build     # compiles to dist/
npm test          # unit + MCP protocol tests against the mock bank (no API needed)

Configuration

The server reads environment variables (see [.env.example](.env.example)):

| Variable | Required | Description | |---|---|---| | `BANK_API_BASE_URL` | yes | e.g. `http://localhost:8080` | | `BANK_API_TOKEN` | one of | A JWT from `POST /api/auth/login` | | `BANK_EMAIL` + `BANK_PASSWORD` | one of | The server logs in itself, and logs in again when the token expires | | `BANK_API_TIMEOUT_MS` | no | Default `5000` | | `LOG_LEVEL` | no | `debug` \| `info` \| `warn` \| `error` (logs go to stderr) |

Use with Claude Desktop

Add this to `claude_desktop_config.json` (on macOS: `~/Library/Application Support/Claude/`), then restart Claude Desktop:

{
  "mcpServers": {
    "banking": {
      "command": "node",
      "args": ["/absolute/path/to/banking-mcp-server/dist/index.js"],
      "env": {
        "BANK_API_BASE_URL": "http://localhost:8080",
        "BANK_EMAIL": "you@example.com",
        "BANK_PASSWORD": "your-password"
      }
    }
  }
}

Then ask something like *"What's the balance of my checking account?"*

Project layout

src/
  index.ts            entry point: config → auth → server → stdio
  config.ts           env parsing and validation (zod)
  auth.ts             token from env, or login with automatic re-login
  bank/client.ts      typed Secure Banking API client
  bank/types.ts       API DTOs
  errors.ts           ToolError: the single error shape returned to the agent
  format.ts           account-number masking, money formatting
  logger.ts           JSON logs to stderr, with secrets redacted
  server.ts           McpServer setup
  tools/readTools.ts  list_accounts, get_balance, list_transactions
test/
  mockBank.ts         MSW mock of the Secure Banking API
  harness.ts          connects a real MCP client to the server in memory
  *.test.ts

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 147 lines
  1. # Banking MCP Server
  2. An [MCP](https://modelcontextprotocol.io) server, written in TypeScript, that lets an AI agent such as
  3. Claude Desktop use the [Secure Banking API](https://github.com/heena5498/secure-banking-application).
  4. The agent can check balances and read transaction history directly, and it can move money only after
  5. the user has confirmed the transfer.
  6. > **Status:** Phase 2 of 7. The three read-only tools work and are tested against a mock bank.
  7. > `transfer`, role-based permissions and the eval come in later phases. See the [roadmap](#roadmap).
  8. ## Why this project
  9. Connecting an LLM to a bank account raises questions that a plain API wrapper doesn't have to answer:
  10. - **Which actions can the agent take on its own?** Reads are safe. Moving money is not.
  11. - **How does it fail?** If the bank is down, the agent should get an error it can explain or retry,
  12. and the server shouldn't crash.
  13. - **Who is allowed to do what?** An administrator and a customer should not see the same tools.
  14. - **How do we know it behaves?** "It worked when I tried it" isn't evidence. A repeatable eval is.
  15. This server answers each of these.
  16. ## What it does
  17. | Tool | Kind | Role | Confirmation |
  18. |---|---|---|---|
  19. | `list_accounts` | read | `CUSTOMER` | No |
  20. | `get_balance` | read | `CUSTOMER` | No |
  21. | `list_transactions` | read | `CUSTOMER` | No |
  22. | `transfer` | **write** | `CUSTOMER` | **Yes, enforced by the server** |
  23. | `admin_list_accounts` | read | `ADMIN` | No |
  24. | `admin_list_transactions` | read | `ADMIN` | No |
  25. - **Confirmed transfers.** `transfer` works in two steps. The first call only returns a preview and a
  26. single-use `confirmationId`. Money moves only when the agent calls again with that ID, after the
  27. user has said yes. The second call must exactly match the preview.
  28. - **Recoverable errors.** Timeouts, network failures and API errors such as `INSUFFICIENT_FUNDS`
  29. become structured tool errors (`code`, `message`, `retryable`, `hint`) that the agent can act on.
  30. - **Role-based tools.** The `roles` claim in the caller's JWT decides which tools are listed. Every
  31. call is checked again, so a hidden tool can't be called by name.
  32. - **Eval.** 10–15 test prompts check that the agent picks the right tool and never transfers without
  33. confirmation.
  34. ## Architecture at a glance
  35. ```mermaid
  36. flowchart LR
  37. U[User] <--> C[Claude Desktop]
  38. C <-- "stdio / JSON-RPC" --> S[Banking MCP Server]
  39. S -- "HTTPS + Bearer JWT" --> A[Secure Banking API<br/>Spring Boot]
  40. A --> D[(PostgreSQL)]
  41. ```
  42. The full design is in the docs:
  43. - [Requirements](docs/requirements.md): what the system must do and how each requirement is verified.
  44. - [Architecture / HLD](docs/architecture.md): components, request flows, the transfer confirmation
  45. protocol, error model and security.
  46. ## Tech stack
  47. Node.js 22 · TypeScript · `@modelcontextprotocol/sdk` · `zod` · Vitest · MSW (mock bank API) ·
  48. Anthropic API (eval)
  49. ## Roadmap
  50. | Phase | Scope
  51. |---|---|
  52. | 1 | Requirements, architecture, HLD, repo setup
  53. | 2 | TypeScript scaffold, API client, read-only tools
  54. | 3 | Failure handling and error mapping
  55. | 4 | JWT role-based tool permissions
  56. | 5 | `transfer` with server-enforced confirmation
  57. | 6 | Eval suite (10–15 prompts)
  58. | 7 | Claude Desktop setup guide, CI, demo
  59. ## Getting started
  60. ### Prerequisites
  61. - Node.js 22+
  62. - A running [Secure Banking API](https://github.com/heena5498/secure-banking-application) (Docker +
  63. Java 25). Not needed for the tests, which use a mock bank.
  64. - Claude Desktop, or any MCP client
  65. ### Install, build and test
  66. ```bash
  67. npm install
  68. npm run build # compiles to dist/
  69. npm test # unit + MCP protocol tests against the mock bank (no API needed)
  70. ```
  71. ### Configuration
  72. The server reads environment variables (see [.env.example](.env.example)):
  73. | Variable | Required | Description |
  74. |---|---|---|
  75. | `BANK_API_BASE_URL` | yes | e.g. `http://localhost:8080` |
  76. | `BANK_API_TOKEN` | one of | A JWT from `POST /api/auth/login` |
  77. | `BANK_EMAIL` + `BANK_PASSWORD` | one of | The server logs in itself, and logs in again when the token expires |
  78. | `BANK_API_TIMEOUT_MS` | no | Default `5000` |
  79. | `LOG_LEVEL` | no | `debug` \| `info` \| `warn` \| `error` (logs go to stderr) |
  80. ### Use with Claude Desktop
  81. Add this to `claude_desktop_config.json` (on macOS: `~/Library/Application Support/Claude/`), then
  82. restart Claude Desktop:
  83. ```json
  84. {
  85. "mcpServers": {
  86. "banking": {
  87. "command": "node",
  88. "args": ["/absolute/path/to/banking-mcp-server/dist/index.js"],
  89. "env": {
  90. "BANK_API_BASE_URL": "http://localhost:8080",
  91. "BANK_EMAIL": "you@example.com",
  92. "BANK_PASSWORD": "your-password"
  93. }
  94. }
  95. }
  96. }
  97. ```
  98. Then ask something like *"What's the balance of my checking account?"*
  99. ### Project layout
  100. ```
  101. src/
  102. index.ts entry point: config → auth → server → stdio
  103. config.ts env parsing and validation (zod)
  104. auth.ts token from env, or login with automatic re-login
  105. bank/client.ts typed Secure Banking API client
  106. bank/types.ts API DTOs
  107. errors.ts ToolError: the single error shape returned to the agent
  108. format.ts account-number masking, money formatting
  109. logger.ts JSON logs to stderr, with secrets redacted
  110. server.ts McpServer setup
  111. tools/readTools.ts list_accounts, get_balance, list_transactions
  112. test/
  113. mockBank.ts MSW mock of the Secure Banking API
  114. harness.ts connects a real MCP client to the server in memory
  115. *.test.ts
  116. ```

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.