ameria-bank

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

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

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