dennisonbertram/mcp-mercury

Mercury MCP Server

A comprehensive Model Context Protocol (MCP) server for Mercury Banking API, providing AI agents with secure access to banking operations through standardized MCP interfaces.

Features

• 🏦 Account Management: View account balances, details, and transaction history
• 💰 Payment Processing: Send ACH/wire payments with validation and idempotency
• 👥 Recipient Management: Create and validate payment recipients with routing info
• 🔐 Permission-Based Access: READ_ONLY vs READ_WRITE token support
• 📊 Real-time Data: Cached responses with configurable TTL
• ✅ Comprehensive Validation: Zod schemas for all API interactions
• 🚀 Multiple Transports: Stdio (CLI) and HTTP/SSE support
• 🛡️ Security First: Token-based auth with permission management

Quick Setup

1. Install Dependencies

npm install
npm run build

2. Configure Environment

Create .env file:

MERCURY_API_TOKEN=secret-token:your_mercury_token_here
MERCURY_API_BASE_URL=https://backend.mercury.com/api/v1  # Optional

3. Add to Claude Code

Local Development

# Add Mercury MCP server to Claude Code
claude mcp add mercury --env MERCURY_API_TOKEN=secret-token:your_token -- node /path/to/mcp-mercury/dist/index.js

# Verify installation
claude mcp list

Project-wide (Shared via .mcp.json)

# Creates .mcp.json for team sharing
claude mcp add --scope project mercury --env MERCURY_API_TOKEN=your_token -- node dist/index.js

User-wide (Available across all projects)

claude mcp add --scope user mercury --env MERCURY_API_TOKEN=your_token -- node dist/index.js

Claude Code Usage Examples

View Account Information

Get my Mercury account balances

Send a Payment

Send $500 to DappHero Corp via wire transfer from my main account

Create a Recipient

Add a new recipient: ABC Company, email: billing@abc.com, with routing number 021000021

Project Structure

mcp-mercury/
├── src/
│   ├── server/
│   │   ├── mcp-server.ts        # Main MCP server
│   │   ├── mercury-client.ts    # Mercury API wrapper
│   │   ├── auth/                # Authentication logic
│   │   ├── resources/           # MCP resources
│   │   ├── tools/               # MCP tools
│   │   ├── transports/          # Transport implementations
│   │   └── utils/               # Utilities and schemas
│   └── index.ts                 # Entry point
├── tests/
│   ├── unit/                    # Unit tests
│   ├── integration/             # Integration tests
│   └── fixtures/                # Test data
├── examples/                    # Usage examples
└── docs/                        # Documentation

Development

Running Tests

# Run all tests
npm test

# Run tests in watch mode
npm run test:watch

# Run with coverage
npm run test:coverage

Building

# Build TypeScript to JavaScript
npm run build

# Clean build artifacts
npm run clean

Linting

npm run lint

Environment Variables

Available Resources

• mercury://accounts - List all accounts with balances and details
• mercury://recipients - List payment recipients with routing info
• mercury://account/{id}/transactions - Account transaction history (prepared for future API)
• mercury://transaction/{id} - Transaction details (prepared for future API)

Available Tools

• mercury_validatePayment - Validate payment parameters before sending
• mercury_sendPayment - Execute ACH/wire payments (requires READ_WRITE token)
• mercury_validateRecipient - Validate recipient information and check duplicates
• mercury_createRecipient - Create new payment recipients (requires READ_WRITE token)

Permission Levels

READ_ONLY Token

• ✅ View accounts and recipients
• ✅ Validate payment/recipient parameters
• ❌ Cannot send payments or create recipients

READ_WRITE Token

• ✅ All READ_ONLY capabilities
• ✅ Send payments and create recipients
• ✅ Full API access

Security

• API tokens are never logged or exposed
• All inputs are validated using Zod schemas
• Idempotency keys prevent duplicate payments
• Permission-based tool exposure (read-only vs read-write)

Error Handling

The server implements comprehensive error handling:

• Authentication errors (401)
• Permission errors (403)
• Resource not found (404)
• Rate limiting (429)
• Network and timeout errors

Testing

The project uses Jest for testing with comprehensive coverage:

• Unit tests for all components
• Integration tests for API interactions
• Mock Mercury API responses for testing
• TDD approach for new features

Troubleshooting

Claude Code Integration Issues

MCP Server Not Found

Ensure the path in the claude mcp add command points to the built dist/index.js file:

# Use absolute path
claude mcp add mercury --env MERCURY_API_TOKEN=your_token -- node /Users/yourname/path/to/mcp-mercury/dist/index.js

Permission Errors

Verify your Mercury API token has the required permissions:

• READ_ONLY tokens can only view data and validate parameters
• READ_WRITE tokens can create recipients and send payments

Connection Issues

Check that your Mercury API token is valid:

curl -H "Authorization: Bearer secret-token:your_token" https://backend.mercury.com/api/v1/accounts

Environment Variable Issues

Ensure your token is properly formatted with the secret-token: prefix:

MERCURY_API_TOKEN=secret-token:mercury_production_xxx...

Contributing

This project follows Test-Driven Development (TDD):

1. Write failing tests first
2. Implement minimal code to pass tests
3. Refactor while keeping tests green
4. Document changes

License

MIT

Support

For issues or questions:

• Create an issue in the repository
• Contact Mercury support for API-specific questions
• Refer to MCP documentation for protocol questions