Mercury MCP Server

An MCP (Model Context Protocol) server for interacting with the Mercury Banking API. This server provides tools to manage bank accounts, transactions, recipients, statements, and other Mercury banking features.

Features

Account Management

• list_accounts - List all bank accounts
• get_account - Get detailed information about a specific account
• get_account_cards - Get cards associated with an account

Transaction Management

• list_transactions - List transactions for an account with filtering options
• get_transaction - Get detailed information about a specific transaction
• create_transaction - Create a new transaction/payment
• request_send_money - Request money from a counterparty

Recipient Management

• list_recipients - List all payment recipients
• get_recipient - Get details of a specific recipient
• create_recipient - Add a new payment recipient
• update_recipient - Update recipient information

Statements & Reports

• get_account_statements - Get account statements
• get_statement_pdf - Download statement as PDF

Additional Services

• get_treasury - Get treasury information
• get_credit - Get credit information

Setup

1. Install Dependencies

npm install

2. Environment Configuration

Copy the example environment file and configure your Mercury API credentials:

cp .env.example .env

Edit .env and add your Mercury API key:

MERCURY_API_KEY=your_mercury_api_key_here
MERCURY_BASE_URL=https://backend.mercury.com/api/v1

# Optional: Use sandbox for testing
# MERCURY_BASE_URL=https://sandbox.mercury.com/api/v1

3. Build the Project

npm run build

4. Run the Server

npm start

For development with auto-reload:

npm run dev

Mercury API Key

To get your Mercury API key:

1. Log into your Mercury dashboard
2. Navigate to API settings
3. Generate a new API token
4. Copy the token to your .env file

Important: Keep your API key secure and never commit it to version control.

Usage Examples

List All Accounts

{
  "tool": "list_accounts",
  "arguments": {}
}

Get Account Transactions

{
  "tool": "list_transactions",
  "arguments": {
    "account_id": "acc_123456789",
    "limit": 50,
    "start_date": "2024-01-01",
    "end_date": "2024-01-31"
  }
}

Create a Transaction

{
  "tool": "create_transaction",
  "arguments": {
    "account_id": "acc_123456789",
    "amount": 100.00,
    "counterparty_id": "recipient_123",
    "note": "Payment for services"
  }
}

Get Specific Transaction Details

{
  "tool": "get_transaction",
  "arguments": {
    "account_id": "acc_123456789",
    "transaction_id": "txn_987654321"
  }
}

Configuration for Claude Desktop

Add this server to your Claude Desktop configuration:

{
  "mcpServers": {
    "mercury": {
      "command": "node",
      "args": ["/path/to/mercury-mcp-server/dist/index.js"],
      "env": {
        "MERCURY_API_KEY": "your_mercury_api_key_here"
      }
    }
  }
}

Rate Limiting

The server implements rate limiting to respect Mercury's API limits:

• Maximum 5 concurrent requests
• 1 second delay between batches
• Automatic request queuing

Error Handling

The server provides comprehensive error handling:

• API authentication errors
• Invalid parameters
• Network timeouts
• Rate limit exceeded

All errors are returned in a standardized format with descriptive messages.

Security

• API keys are loaded from environment variables
• No sensitive data is logged
• All requests use HTTPS
• Bearer token authentication

Development

Project Structure

mercury-mcp-server/
├── src/
│   ├── index.ts          # Main server entry point
│   ├── api.ts            # API client with rate limiting
│   ├── types.ts          # TypeScript type definitions
│   ├── utils.ts          # Helper functions
│   └── tools/            # Feature-specific tools
│       ├── accounts.ts
│       ├── transactions.ts
│       ├── recipients.ts
│       ├── statements.ts
│       ├── treasury.ts
│       └── credit.ts
├── package.json
├── tsconfig.json
└── README.md

Adding New Tools

1. Create a new file in src/tools/
2. Export tool objects with schema and handler properties
3. Register the tools in src/index.ts

Testing

For testing, use Mercury's sandbox environment by setting:

MERCURY_BASE_URL=https://sandbox.mercury.com/api/v1

Support

For issues with this MCP server, please check:

1. Your Mercury API key is valid and has the required permissions
2. Environment variables are properly configured
3. Network connectivity to Mercury's API

For Mercury API-specific questions, refer to the Mercury API Documentation.

License

This project is licensed under the MIT License.