nium-global/mcp-server-sandbox

Nium MCP Server (Sandbox)

A sample Model Context Protocol (MCP) server implementation that demonstrates integration with key Nium APIs in the sandbox environment for financial services, money transfers, and beneficiary management.

📋 Features

Beneficiary Management

• List Beneficiaries: Retrieve existing beneficiaries with search and pagination
• Create Beneficiaries: Automatically generate beneficiary data using validation schemas
• Update Beneficiaries: Modify existing beneficiary information with comprehensive field support
• Smart Search: Find beneficiaries by name or ID with fuzzy matching

Money Transfers

• Send Money: Transfer funds with automatic beneficiary verification and confirmation workflow
• Smart Confirmation: Two-step confirmation process for both new and existing beneficiaries
• Transaction History: Retrieve wallet transaction history with filtering options

Validation & Schemas

• Beneficiary Schemas: Get validation schemas for different countries, currencies, and payout methods
• Sample Data Generation: Automatically generate sample payloads based on API schemas

📦 Installation

1. Clone the repository:

   git clone git@github.com:nium-global/mcp-server-sandbox.git
   cd mcp-server-sandbox
   

2. Install dependencies:

   install uv

   brew install uv
   uv sync
   

   Or using pip:

 pip install -r requirements.txt   

3. Set up environment variables:

   Create a .env file in the project root with your Nium API credentials:

   API_KEY=your_nium_api_key
   CLIENT_ID=your_client_id
   CUSTOMER_ID=your_customer_id
   WALLET_ID=your_wallet_id
   

4. Congfigure Claude Desktop:

   Add the following configuration to your Claude Desktop config file:

   macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

   Windows: %APPDATA%\Claude\claude_desktop_config.json

   {
   "mcpServers": {
      "nium": {
         "command": "/path/to/your/uv",
         "args": [
         "--directory",
         "/path/to/your/mcp-server-sandbox",
         "run",
         "nium_mcp.py"
         ]
      }
   }
   }
   

   Go to the settings menu. Under Developer, select Edit Config.

5. Launch Claude

   You will now be able to see Nium in the prompt options menue

   You can also see what tools are enabled within the Nium MCP connection

   Try prompting Claude for Nium specific use cases.

   Use case examples:

   1. Querying Beneficiaries
   2. Sending Money
   3. List transactions
   4. Update Beneficiaries

Environment Configuration

Required Environment Variables

All environment variables should be added to a .env file in the project root directory. This file is automatically loaded when the MCP server starts.

API_KEY (Required)

Your Nium API authentication key.

• Where to find: Nium Portal → API Keys section
• Format: String (e.g., 41b2PYr9KV92kvBq8GUqY6LTppOsg812334HAjd3)
• Used for: Authenticating all API requests to Nium

CLIENT_ID (Required)

Your Nium client identifier, also referred to as clientHashId in API documentation.

• Where to find: Nium Portal → API Keys section
• Format: UUID (e.g., 3bb47cf1-ec41-4159-8b12-ad5bf246d04d)
• Used for: Identifying your client in API endpoints

CUSTOMER_ID (Required)

Your Nium customer identifier, also referred to as customerHashId in API documentation.

• Where to find: Nium Portal → Customer Balances
• Format: UUID (e.g., 0ad3e0e3-d30d-4c49-ac95-72d563ba5e37)
• Used for: Beneficiary management and transaction operations

WALLET_ID (Required)

Your Nium wallet identifier, also referred to as walletHashId in API documentation.

• Where to find: Nium Portal → Customer Balances
• Format: UUID (e.g., eac1c866-f12c-47ee-8344-a1365b043d47)
• Used for: Money transfers and transaction history

Sample .env File

# Nium API Configuration
API_KEY=41b2PYr9KV92kvBq8GUqY6LTppOsg812334HAjd3
CLIENT_ID=3bb47cf1-ec41-4159-8b12-ad5bf246d04d
CUSTOMER_ID=0ad3e0e3-d30d-4c49-ac95-72d563ba5e37
WALLET_ID=eac1c866-f12c-47ee-8344-a1365b043d47

Environment Setup Steps

1. Create the .env file:

   touch .env
   

2. Add your credentials: Open the .env file in a text editor and add your actual Nium credentials:

   nano .env
   # or
   code .env
   

3. Verify the configuration: The MCP server will validate all required environment variables on startup and provide clear error messages if any are missing.

Security Notes

• Never commit your .env file to version control
• The .env file should be added to your .gitignore
• Keep your API credentials secure and rotate them regularly
• Use different credentials for development, staging, and production environments

Environment Variable Validation

The MCP server includes built-in validation that will:

• ✅ Check for all required environment variables on startup
• ✅ Provide clear error messages for missing variables
• ✅ Mask sensitive information (API keys) in debug output
• ✅ Validate credential format before making API calls

If any required environment variables are missing, you'll see an error like:

Missing required environment variables: CLIENT_ID, WALLET_ID

MCP Client Integration

Claude Desktop

Add the following configuration to your Claude Desktop config file:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "nium": {
      "command": "/path/to/your/uv",
      "args": [
        "--directory",
        "/path/to/your/mcp-server-sandbox",
        "run",
        "nium_mcp.py"
      ]
    }
  }
}

Generic MCP Client

For any MCP-compatible client:

python nium_mcp.py

Or using uv:

uv run nium_mcp.py

📋 Available Tools

1. get_beneficiary_schema

Retrieve validation schemas for creating beneficiaries.

Parameters:

• currencyCode (string): Currency code (e.g., "USD")
• destinationCountry (string): Destination country code (e.g., "US")
• payoutMethod (string): Payout method (e.g., "BANK_TRANSFER")

Example:

get_beneficiary_schema(
    currencyCode="EUR",
    destinationCountry="DE", 
    payoutMethod="SWIFT"
)

2. list_beneficiaries

Retrieve existing beneficiaries with optional filtering.

Parameters:

• page (int, optional): Page number (default: 0)
• size (int, optional): Results per page (default: 20, max: 100)
• search (string, optional): Search term
• status (string, optional): Filter by status

Example:

list_beneficiaries(page=0, size=10, search="John")

3. create_beneficiary

Create a new beneficiary with automatic schema validation.

Parameters:

• beneficiary_name (string): Beneficiary name
• currency_code (string): Currency code
• country_code (string): Country code
• payout_method (string): Payout method
• beneficiary_data (dict, optional): Custom beneficiary data

Example:

create_beneficiary(
    beneficiary_name="John Doe",
    currency_code="USD",
    country_code="US",
    payout_method="BANK_TRANSFER"
)

4. update_beneficiary

Update existing beneficiary information.

Parameters:

• beneficiary_hash_id (string): Beneficiary ID to update
• beneficiary_data (dict, optional): Complete update data
• Plus 40+ individual field parameters for specific updates

Example:

update_beneficiary(
    beneficiary_hash_id="68bfc6e715e69a63f748d684",
    beneficiary_name="John Smith Updated",
    beneficiary_email="john.updated@example.com"
)

5. send_money

Send money with automatic beneficiary verification and confirmation.

Parameters:

• beneficiary_name_or_id (string): Beneficiary name or ID
• source_amount (float): Amount to send
• source_currency (string): Source currency
• country_code (string, optional): Country for new beneficiaries
• payout_method (string, optional): Payout method for new beneficiaries
• purpose_code (string, optional): Transaction purpose
• source_of_funds (string, optional): Source of funds
• exemption_code (string, optional): Exemption code
• own_payment (bool, optional): Own payment flag
• confirm_send (bool): Confirm money transfer
• confirm_create (bool): Confirm beneficiary creation

Example Workflow:

1. Initial call:

   send_money(
       beneficiary_name_or_id="John Doe",
       source_amount=100.0,
       source_currency="USD"
   )
   

2. If beneficiary exists, confirm transfer:

   send_money(
       beneficiary_name_or_id="John Doe",
       source_amount=100.0,
       source_currency="USD",
       confirm_send=True
   )
   

3. If new beneficiary, confirm creation then transfer:

   # Step 1: Confirm creation
   send_money(
       beneficiary_name_or_id="Jane Doe",
       source_amount=100.0,
       source_currency="USD",
       confirm_create=True
   )
   
   # Step 2: Confirm transfer
   send_money(
       beneficiary_name_or_id="Jane Doe",
       source_amount=100.0,
       source_currency="USD",
       confirm_create=True,
       confirm_send=True
   )
   

6. get_wallet_transactions

Retrieve wallet transaction history.

Parameters:

• page (int, optional): Page number
• size (int, optional): Results per page
• start_date (string, optional): Start date (YYYY-MM-DD)
• end_date (string, optional): End date (YYYY-MM-DD)
• transaction_type (string, optional): Transaction type
• status (string, optional): Transaction status
• currency_code (string, optional): Currency filter
• system_reference_number (string, optional): System reference
• customer_reference_number (string, optional): Customer reference

Example:

get_wallet_transactions(
    page=0,
    size=20,
    start_date="2024-01-01",
    end_date="2024-12-31",
    status="COMPLETED"
)

Safety Features

Confirmation Workflow

• Double Confirmation: All money transfers require explicit confirmation
• New Beneficiary Safety: Two-step process for new beneficiaries (create � confirm transfer)
• Transfer Details: Shows amount, currency, and recipient before confirmation
• Beneficiary Verification: Automatically searches for existing beneficiaries to prevent duplicates

API Coverage

This MCP server covers the following Nium API endpoints: