Skip to main content
Glama
ameria-bank

ameria-bank

by melontron

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

Related MCP server: MBBank MCP Server

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)

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
  1. 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

Available Tools

5 tools
get_account_eventsA
Read-onlyIdempotent

Get past events (transactions) for a specific Ameria Bank account. Filters by account and minimum amount. Use get_accounts_and_cards first to find the accountId — use the 'accountId' field from cards or 'id' field from accounts (e.g. '31023550200').

Inputs: accountIds (required), page, size, fromAmount.

get_accounts_and_cardsA
Read-onlyIdempotent

Get all accounts and cards from Ameria Bank. Returns balances, card types, statuses, overdraft info, and product IDs. Includes both Ameria cards and linked external cards. Call this FIRST to discover available account/card IDs before using get_available_balance or get_account_events.

Inputs: no named parameters.

get_available_balanceA
Read-onlyIdempotent

Get detailed balance breakdown for a specific card or account. Returns balance, available balance, frozen balance, and offline available amount. Use get_accounts_and_cards first to find the product ID.

Inputs: productId (required), productType.

get_transactionsA
Read-onlyIdempotent

Get transaction history from Ameria Bank. Returns a page of transactions within a date range. Defaults to last 30 days. Use page parameter to paginate — check hasNext in the response to know if more pages exist. For finding specific merchants, prefer search_transactions instead.

Inputs: page, size, toDate, fromDate.

search_transactionsA
Read-onlyIdempotent

Search Ameria Bank transactions by keyword within a date range. Filters against merchant names, transfer descriptions, and beneficiary names (case-insensitive). IMPORTANT: searches within a single page only — to find all matches, iterate through pages or use a larger page size. Useful for questions like 'how much did I spend on YANDEX this month?'.

Inputs: query (required), page, size, toDate, +1 more.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A4.1/5.0

    Scored across 5 tools

    Disambiguation3/5

    get_transactions and get_account_events both retrieve transactions—one broadly, one per account—creating overlap. search_transactions provides keyword filtering but its single-page limitation blurs its boundaries with get_transactions. get_available_balance is distinct, but the transaction trio causes moderate ambiguity.

    Naming Consistency4/5

    Most tool names follow a consistent verb_noun pattern (get_transactions, search_transactions, get_accounts_and_cards, get_available_balance, get_account_events). However, 'get_accounts_and_cards' deviates by returning two resource types, slightly breaking the pattern.

    Tool Count5/5

    With only 5 tools, the set is well-scoped for a bank integration, covering browsing accounts, checking balances, and retrieving/searching transactions without bloat.

    Completeness3/5

    The surface covers read operations for accounts and transactions but lacks any write capabilities (e.g., transfers, payments) and missing account details like statements or card management. This is a notable gap for a banking domain.

    Maintenance

    ActivityInactive
    ResponsivenessOutdated data

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      Not graded
      quality
      D
      maintenance
      MCP server that provides monitoring and analytics capabilities for MBBank accounts, allowing users to check balances, transaction history, card details, and savings information.
      7
      MIT
    • A
      license
      Not graded
      quality
      D
      maintenance
      An MCP server that enables AI assistants to retrieve and format Monobank account statements and transactions by date range.
      8 npm
      5
      MIT