finance MCP Server
Official MCP server for Agent payment infrastructure for AI agents. MCP server for autonomous stablecoin transfers, currency swaps & agent wallets. Works with Claude, LangChain, CrewAI. Settled on Hedera.
Discovered via github-topic:model-context-protocol and last synced 3mo ago.
1. Install the package
npx @bananacrystal/mcp-server
2. Add to claude_desktop_config.json
{
"mcpServers": {
"-bananacrystal-mcp-server": {
"command": "npx",
"args": [
"@bananacrystal/mcp-server"
]
}
}
}Config file location: ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) / %APPDATA%\Claude\claude_desktop_config.json (Windows)
Server version and environment
Calculate fees before swapping
Single offer details
Swap between any two supported stablecoins
Permanently delete offer
What it does
Token
What we need
Fee
Live buy/sell rates for any currency
Full escrow transaction history
All supported stablecoins
Fiat deposit status by transfer ID
Single trade details
Paginated transaction log with filters
Escrow balance breakdown
Withdraw to bank account
Your offers
Health check
API key spending limits and current usage
Your trades
Step 2: Execute transfer with OTP
Fiat withdrawal requests
Execute after approval
No
Token balances (all or specific token)
KYC verification status
Deposit via ACH or wire
**Yes**
What it does
Edit an offer (before any trades)
Volume
Browse prediction market offers
Remove offer from marketplace
Reset fake balances to defaults
Contact us
Your profile, wallets, and MCP key info
Status of a pending approval request
Browse all trades
Start KYC verification
Cancel an active trade
Required
**[View all 150+ supported currencies →](./CURRENCIES.md)** Use `list_available_tokens` to get the live list with Hedera token IDs and current exchange rates. </details> <details> <summary><b>What is Hedera and why does it matter for agent payments?</b></summary> Hedera is an enterprise-grade public distributed ledger chosen for three properties critical to autonomous agent payments: - **Absolute finality in under 5 seconds**: Unlike Ethereum's probabilistic finality or Bitcoin's 10-minute blocks, Hedera's hashgraph consensus provides certainty that a transaction has cleared. An agent's next action depends on knowing the payment settled, making absolute finality a functional requirement rather than a preference. - **Low transaction fees**: Hedera's fee structure makes agent micropayments economically viable at scale. No other production blockchain offers this combination of speed and cost. - **Carbon-negative network**: This is the only carbon-negative public distributed ledger, which matters for enterprises running agents at millions of transactions per month. </details> <details> <summary><b>Is the MCP server open source? Can I self-host it?</b></summary> Yes, it is MIT licensed. The server is a thin authenticated client that makes HTTP requests to BananaCrystal's API. You can fork it, modify it, and run it locally. A mock server is included for development without a real API key. To run locally without an API key: ```bash git clone https://github.com/BananaCrystal/mcp-server-bananacrystal.git cd mcp-server-bananacrystal npm install && npm run mock ``` The mock server returns realistic data so you can build integrations, write tests, and explore all 40 tools without touching production. </details> <details> <summary><b>What is the agent economy?</b></summary> The agent economy is the emerging economic layer where AI agents participate as independent economic actors. They are not just tools that assist humans, but participants that earn, spend, negotiate, and operate on their own financial behalf. It requires three new infrastructure primitives: **agent wallets** (programmatic identity, no human KYC), **autonomous payments** (programmatic spending policy, not per-transaction human approval), and **machine-speed settlement** (on-chain, under 5 seconds, machine-readable confirmation). BananaCrystal is the agent payment infrastructure layer. We don't sell a product; we represent a category called **AI-native finance**, which is a financial system built for machines rather than adapted from one built for humans. The agent economy is forming now, and developers who integrate payment rails first will define how it works. </details> <details> <summary><b>How do I report a security vulnerability?</b></summary> Do not open a public GitHub issue for security vulnerabilities. Email [email protected] with: 1. Description of the vulnerability 2. Steps to reproduce 3. Potential impact We will acknowledge within 24 hours and aim to resolve critical issues within 72 hours. We do not currently have a formal bug bounty program but we recognize responsible disclosures publicly and in our changelog. </details> <details> <summary><b>Is there a sandbox environment for testing?</b></summary> Yes, and you should always start there. Create a **Sandbox key** at [agents.bananacrystal.com/account](https://agents.bananacrystal.com/account) → API Keys → Create Sandbox Key. Sandbox keys start with `bc_test_` so you can always tell them apart from live keys (which have no prefix). The package automatically routes each key to the correct endpoint. **What sandbox gives you:** - Pre-seeded balances: 10,000 USDb · 5,000,000 NGNb · 50,000 GHSb · 1,000,000 KESb · 150,000 ZARb - OTP codes are returned directly in the API response, so there is no email sent and no waiting - KYC always approved instantly - Spending limits are unlimited - Reset balances anytime with the `reset_sandbox_balance` tool All 40 MCP tools work identically in sandbox. Additionally, **rate service endpoints** are available in sandbox at `/mcp/sandbox/rate/*` without requiring authentication, which is perfect for testing currency exchange operations. When you're ready to go live, swap `bc_test_your_key` for a live key. It uses the same configuration and tools but with real money. There is also a **local mock server** for contributors who want to develop without any API key at all: ```bash git clone https://github.com/BananaCrystal/mcp-server-bananacrystal.git cd mcp-server-bananacrystal npm install && npm run mock ``` The mock server runs on `http://localhost:3000` and returns realistic data for all tools. </details> <details> <summary><b>What is the rate service? How is it different from MCP tools?</b></summary> The **rate service** is a separate backend HTTP API (not part of the 40 MCP tools). It provides comprehensive currency exchange operations: - List all supported currencies - Get current exchange rates between any two currencies - Convert amounts instantly - Batch convert multiple currency pairs - Retrieve historical rate data over date ranges - Get rate statistics (high/low/average) **Key difference:** MCP tools are accessed through the MCP server interface (as described above). The rate service is accessed directly via HTTP REST endpoints. **How to use rate service:** 1. Create an API key with `rate` scope at [agents.bananacrystal.com/account](https://agents.bananacrystal.com/account) 2. Call rate endpoints directly: ```bash curl -H "x-api-key: bc_live_your_key_with_rate_scope" \ "https://agentic.bananacrystal.com/api/v1/mcp/rate/current?from=USD&to=NGN" ``` **Sandbox testing:** Use `/mcp/sandbox/rate/*` endpoints (no authentication required). **When to use rate service vs MCP tools:** - Use rate service for standalone rate lookups or integration into backend systems - Use MCP tools for autonomous agent workflows with full payment capabilities - They are complementary, so you can use both if you need rates and payments See [Backend rate service](#backend-rate-service-separate-from-mcp-tools) section for full endpoint reference. </details> <details> <summary><b>What CLI tools are available?</b></summary> After installing the package globally (`npm install -g @bananacrystal/mcp-server`), the `bananacrystal-mcp` binary is available on your PATH. **Primary use: Running the MCP server** ```bash bananacrystal-mcp # Starts the MCP server over stdio, ready for Claude Desktop or any MCP client ``` **Check version:** ```bash bananacrystal-mcp --version ``` **Debug mode: Verbose logging to stderr** ```bash DEBUG=true bananacrystal-mcp ``` **Override the API endpoint (e.g. point to local mock):** ```bash BANANACRYSTAL_API_URL=http://localhost:3001 bananacrystal-mcp ``` **Test with MCP Inspector (interactive tool explorer):** ```bash export BANANACRYSTAL_API_KEY=bc_test_your_key_here npx @modelcontextprotocol/inspector node dist/index.js ``` The MCP Inspector opens a browser UI where you can call any of the 40 tools interactively. This is useful for exploring the API before wiring it into an agent. </details> <br/> --- ## Development and local testing ```bash # Clone git clone https://github.com/BananaCrystal/mcp-server-bananacrystal.git cd mcp-server-bananacrystal # Install npm install # Start mock server: No API key needed # All 40 MCP tools + rate service endpoints return realistic mock data npm run mock # Build from source npm run build # Run in development mode (requires real API key with appropriate scopes) export BANANACRYSTAL_API_KEY=bc_test_your_sandbox_key npm run dev # Test rate service endpoints on mock server (no auth needed): curl http://localhost:3001/api/v1/mcp/sandbox/rate/currencies curl http://localhost:3001/api/v1/mcp/sandbox/rate/current?from=USD&to=NGN # Test with MCP Inspector (for 40 MCP tools) export BANANACRYSTAL_API_KEY=bc_test_your_key_here npx @modelcontextprotocol/inspector node dist/index.js ``` **Configure your agent to use the mock server (includes rate service):** ```json { "mcpServers": { "bananacrystal": { "command": "bananacrystal-mcp", "env": { "BANANACRYSTAL_API_KEY": "bc_mock_test", "BANANACRYSTAL_API_URL": "http://localhost:3001" } } } } ``` <br/> --- ## Troubleshooting <details> <summary><b>"API key invalid"</b></summary> - Verify the key is copied correctly from [agents.bananacrystal.com/account](https://agents.bananacrystal.com/account) - Sandbox keys start with `bc_test_` for testing without real money. Live keys have no prefix. - Verify key is active at [agents.bananacrystal.com/account](https://agents.bananacrystal.com/account) → API Keys - Check the key has the required scope for the tool being called (`transfer` scope for `transfer_tokens`, `swap` scope for `swap_currency`, `rate` scope for rate service) - Check for whitespace or truncation in the environment variable </details> <details> <summary><b>"Spending limit exceeded"</b></summary> This is working as designed; limits are enforced at the infrastructure level and cannot be bypassed. To increase limits: [agents.bananacrystal.com/account](https://agents.bananacrystal.com/account) → API Keys → Edit → adjust daily cap or per-transaction maximum. If you are building a production agent, set limits conservatively first and increase after observing real usage patterns. </details> <details> <summary><b>MCP server not appearing in Claude / Cursor</b></summary> 1. Validate config file is valid JSON at [jsonlint.com](https://jsonlint.com) 2. Confirm file is at the correct path for your OS 3. Restart the application completely (full quit, not just reload) 4. Check the application's MCP logs for the exact error message </details> <details> <summary><b>OTP not received</b></summary> - Check spam/junk folder for email from BananaCrystal - OTP expires in 10 minutes, so request a fresh one if needed - Verify your registered email at [agents.bananacrystal.com/account](https://agents.bananacrystal.com/account) </details> <details> <summary><b>"Rate limit exceeded"</b></summary> - Implement exponential backoff in your agent retry logic - The error response includes a `retry_after` field in seconds, which you should respect - For high-volume production agents, contact support to increase rate limits </details> <details> <summary><b>"Rate service returning 401 Unauthorized"</b></summary> Rate service endpoints (`/api/v1/mcp/rate/*` and `/api/v1/mcp/sandbox/rate/*`) require keys with `rate` scope: - Create a new key at [agents.bananacrystal.com/account](https://agents.bananacrystal.com/account) - When creating the key, enable `rate` scope - Sandbox rate endpoints (`/mcp/sandbox/rate/*`) require no authentication, so you can use them for free testing </details> <br/> --- ## Contributing **We are building the financial infrastructure of the agent economy. This is early. Your contributions shape the category.** ```bash git clone https://github.com/BananaCrystal/mcp-server-bananacrystal.git cd mcp-server-bananacrystal npm install npm run mock # develop against mock: No API key needed npm run dev ``` ### What to work on The highest-impact contributions right now:
Request a transaction from another user's agent
No
All Hedera token IDs
Step 1: Request OTP code (email in live, returned directly in sandbox)
Create a prediction market offer
Configure approval rules and webhook URL
Echo a message
Look up another agent's payment config
Trade against an offer
Mechanism
Connect to Helium's MCP server for news research, media bias analysis, balanced perspectives, stock/options data, and semantic meme search across 3.2M+ articles and 5,000+ sources
Automate account reconciliation by matching transactions, identifying discrepancies, and generating variance reports
Create comprehensive business plans, financial projections, and strategic documents for funding or planning
Calculate cash runway, burn rate, and financial sustainability projections
TradingAgents: Multi-Agents LLM Financial Trading Framework
Build your autonomous hedge fund in minutes. AutoHedge harnesses the power of swarm intelligence and AI agents to automate market analysis, risk management, and trade execution.
💰 Double-entry bookkeeping made easy — plain-text accounting for humans and AI agents. Polished iOS & Android app built with React Native + Expo.
Pizzly, financial market analysis combining technical indicators with LLMs, featuring real-time data processing and AI-powered market insights ⚡️
Learn how to use the Financial Analyst Claude skill. Complete guide with installation instructions and examples.
Learn how to use the helium-mcp Claude skill. Complete guide with installation instructions and examples.
Learn how to use the Runway Calculator Claude skill. Complete guide with installation instructions and examples.