ameria-bank
Allows secure storage of refresh tokens and automatic token rotation via 1Password vault.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@ameria-bank Show my recent transactions"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
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 |
| Transaction history with date range and pagination |
| Search transactions by merchant/keyword |
| All accounts, cards, balances, overdraft info |
| Detailed balance breakdown for a specific card/account |
| 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.
Log in to MyAmeria
Open browser Developer Tools (F12 or Cmd+Option+I)
Go to the Network tab, filter by
tokenLook for a request to
account.myameria.am/auth/realms/ameria/protocol/openid-connect/tokenIn the response, copy the
refresh_tokenvalueStore 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 |
| Yes* | Refresh token from MyAmeria. *Not required if using a vault. |
| Yes* | Base64-encoded |
| Yes* | Client-Id header value for API calls. *Not required if using a vault. |
| No | Vault backend: |
| No | Item name in the vault (e.g. |
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.
Create an item called
ameria-mcpin 1PasswordAdd these fields:
refresh_token— your refresh tokenclient_auth— Base64-encodedclient_id:client_secret(from the Authorization header in the token request)client_id— the Client-Id UUID (from the API request headers)
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
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" -UConfigure 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 installRun locally:
AMERIA_TOKEN=your_token node server.jsTest with MCP Inspector:
AMERIA_TOKEN=your_token npm run inspectRunning Tests
npm test104 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.jsThen 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 toolsget_account_eventsARead-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_cardsARead-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_balanceARead-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_transactionsARead-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_transactionsARead-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
Scored across 5 tools
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.
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.
With only 5 tools, the set is well-scoped for a bank integration, covering browsing accounts, checking balances, and retrieving/searching transactions without bloat.
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
Related MCP Connectors
MCP server unifying ERPs, CRMs, APIs and knowledge base for Claude, ChatGPT and Gemini.
MCP server enabling AI agents to manage Bitrix24 features via standardized protocol
One MCP server for the services your AI needs: memory, files, Microsoft 365, kanban and more.
MCP server that lets your AI assistant build and deploy apps, hosting each one at a live URL.
Related MCP Servers
- FlicenseNot gradedqualityDmaintenanceAn MCP Server that provides a conversational interface to the UK Open Banking account information API, allowing agents to interact with bank account data through natural language commands.-
- AlicenseNot gradedqualityDmaintenanceMCP server that provides monitoring and analytics capabilities for MBBank accounts, allowing users to check balances, transaction history, card details, and savings information.7MIT
- AlicenseAqualityDmaintenanceAn MCP server that enables AI assistants to automate Cash App payments, balance checks, and transaction management via browser automation.13MIT
- AlicenseNot gradedqualityDmaintenanceAn MCP server that enables AI assistants to retrieve and format Monobank account statements and transactions by date range.8 npm5MIT