ameria-bank

<p align="center"> <img src="logo.jpg" alt="Ameria Bank" width="120" /> </p>

<h1 align="center">Ameria Bank MCP Server</h1>

<p align="center"> <a href="https://opensource.org/licenses/MIT"><img src="https://img.shields.io/badge/License-MIT-yellow.svg" alt="License: MIT" /></a> <img src="https://img.shields.io/badge/tests-104%20passed-brightgreen.svg" alt="Tests: 104 passed" /> </p>

Unofficial. This project is not affiliated with, endorsed by, or associated with Ameria Bank. It is an independent open-source tool that uses the publicly accessible MyAmeria online banking interface.

Open-source MCP server for Ameria Bank online banking. Query your transaction history, account balances, and card info — all through AI assistants like Claude Desktop.

Read-only. This server only reads data from your accounts. It cannot initiate transfers, payments, or modify anything.

Available Tools

Tool	Description
get_transactions	Transaction history with date range and pagination
search_transactions	Search transactions by merchant/keyword
get_accounts_and_cards	All accounts, cards, balances, overdraft info
get_available_balance	Detailed balance breakdown for a specific card/account
get_account_events	Per-account transaction events with filtering

Setup

1. Get Your Refresh Token

The server uses a refresh token to automatically obtain short-lived access tokens. You only need to set this up once — the refresh token is long-lived and the server handles token rotation automatically.

1. Log in to MyAmeria
2. Open browser Developer Tools (F12 or Cmd+Option+I)
3. Go to the Network tab, filter by token
4. Look for a request to account.myameria.am/auth/realms/ameria/protocol/openid-connect/token
5. In the response, copy the refresh_token value
6. Store it in a secure vault (1Password, macOS Keychain, etc.)

Note: The refresh token lasts much longer than the 15-minute access token. The server automatically refreshes the access token when it expires, so you don't need to manually update tokens for each session.

2. Configure Claude Desktop

Add to ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) or %APPDATA%\Claude\claude_desktop_config.json (Windows):

Option A — Vault (recommended, token auto-rotates):

{
  "mcpServers": {
    "ameria-bank": {
      "command": "node",
      "args": ["/absolute/path/to/ameria-mcp/server.js"],
      "env": {
        "AMERIA_VAULT": "keychain",
        "AMERIA_VAULT_KEY": "ameria-mcp"
      }
    }
  }
}

Option B — Env var (simpler, but tokens don't persist across rotations):

{
  "mcpServers": {
    "ameria-bank": {
      "command": "node",
      "args": ["/absolute/path/to/ameria-mcp/server.js"],
      "env": {
        "AMERIA_TOKEN": "your_refresh_token"
      }
    }
  }
}

Restart Claude Desktop after saving.

Usage Examples

Once connected, you can ask Claude things like:

• "Show my recent transactions"
• "How much did I spend on Yandex Go this month?"
• "What are my card balances?"
• "Show me all transactions over 10,000 AMD last week"
• "What's my available balance on the Visa Signature card?"
• "List all spending on groceries this month"

Environment Variables

Variable	Required	Description
AMERIA_TOKEN	Yes*	Refresh token from MyAmeria. *Not required if using a vault.
AMERIA_CLIENT_AUTH	Yes*	Base64-encoded client_id:client_secret for the token endpoint. *Not required if using a vault.
AMERIA_CLIENT_ID	Yes*	Client-Id header value for API calls. *Not required if using a vault.
AMERIA_VAULT	No	Vault backend: 1password or keychain
AMERIA_VAULT_KEY	No	Item name in the vault (e.g. ameria-mcp)

Vault Integration (Recommended)

Store the refresh token in a vault instead of an env var. The server reads from the vault on startup and automatically saves rotated refresh tokens back — so you never have to manually update the token again.

1Password

Requires the 1Password CLI (op) with biometric unlock or service account.

1. Create an item called ameria-mcp in 1Password
2. Add these fields:
   • refresh_token — your refresh token
   • client_auth — Base64-encoded client_id:client_secret (from the Authorization header in the token request)
   • client_id — the Client-Id UUID (from the API request headers)
3. Configure Claude Desktop:

{
  "mcpServers": {
    "ameria-bank": {
      "command": "node",
      "args": ["/absolute/path/to/ameria-mcp/server.js"],
      "env": {
        "AMERIA_VAULT": "1password",
        "AMERIA_VAULT_KEY": "ameria-mcp"
      }
    }
  }
}

The server reads refresh_token, client_auth, and client_id from the item via op item get and writes back rotated refresh tokens with op item edit.

macOS Keychain

1. Store the credentials:

security add-generic-password -s ameria-mcp -a refresh_token -w "YOUR_REFRESH_TOKEN" -U
security add-generic-password -s ameria-mcp -a client_auth -w "YOUR_BASE64_CLIENT_AUTH" -U
security add-generic-password -s ameria-mcp -a client_id -w "YOUR_CLIENT_ID_UUID" -U

2. Configure Claude Desktop:

{
  "mcpServers": {
    "ameria-bank": {
      "command": "node",
      "args": ["/absolute/path/to/ameria-mcp/server.js"],
      "env": {
        "AMERIA_VAULT": "keychain",
        "AMERIA_VAULT_KEY": "ameria-mcp"
      }
    }
  }
}

The server reads refresh_token, client_auth, and client_id from Keychain (service=ameria-mcp) and writes back rotated refresh tokens automatically.

No Vault (env only)

If AMERIA_VAULT is not set, the server uses AMERIA_TOKEN env var directly. Rotated tokens are kept in memory only and not persisted — you'll need to update the token manually if the refresh token expires.

Development

git clone <repo-url>
cd ameria-mcp
npm install

Run locally:

AMERIA_TOKEN=your_token node server.js

Test with MCP Inspector:

AMERIA_TOKEN=your_token npm run inspect

Running Tests

npm test

104 tests covering all helper functions: date validation, card/account masking, currency grouping, transaction formatting, and error handling.

Claude Code

claude mcp add ameria-bank -- node /absolute/path/to/ameria-mcp/server.js

Then set AMERIA_TOKEN in your environment.

Security

• Read-only — no write operations, no transfers, no payments
• Access tokens auto-refresh — the server uses a refresh token to obtain short-lived access tokens automatically
• Card numbers are masked — double-masked even though the API already partially masks them
• 30-second request timeout — prevents indefinite hangs
• No data persistence — nothing is cached or stored locally

License

MIT