global-alipayplus-mcp

AlipayPlus MCP Server

A Model Context Protocol (MCP) compatible server that integrates Ant International's AlipayPlus payment APIs, enabling AI assistants to handle payment and refund operations seamlessly.

Overview

The AlipayPlus MCP Server wraps Ant International's AlipayPlus payment APIs into standardized MCP tools, allowing AI assistants to securely process payment-related operations during conversations. With this server, you can create payments, query transaction status, handle refunds, and more directly through AI interactions.

Features

💳 Payment Operations

• Create Payment (create_payment): Generate payment requests for processing transactions
• Query Payment (query_payment): Retrieve transaction status and information for submitted payment requests
• Cancel Payment (cancel_payment): Cancel payments when results are not returned within expected timeframes

💰 Refund Operations

• Create Refund (create_refund): Initiate full or partial refunds against successful payments

🛃 Customs Operations

• Customs Declare (customs_declare): Declare a payment to customs or update an existing declaration
• Query Customs Declaration (query_customs_declare): Inquire about the status of declared payments

Prerequisites

Before using the AlipayPlus MCP Server, ensure you have:

• Python 3.11 or higher
• uv (recommended package manager) or pip
• Valid AlipayPlus Merchant Account with:
  • Merchant Client ID (CLIENT_ID)
  • Merchant RSA Private Key (MERCHANT_PRIVATE_KEY)
  • Alipay RSA Public Key (ALIPAY_PUBLIC_KEY)
  • Payment Notification Callback URL (PAYMENT_NOTIFY_URL)

Quick Start

1. Installation

Direct Usage with uvx (Recommended)

uvx ant-intl-alipayplus-mcp

Install with pip

pip install ant-intl-alipayplus-mcp

Install with uv

uv install ant-intl-alipayplus-mcp

Install from Source

git clone https://github.com/alipay/global-alipayplus-mcp.git
cd global-alipayplus-mcp
uv install

Requirements

• Python 3.11 or higher
• Dependencies:
  • cryptography==44.0.3
  • mcp[cli]>=1.9.1
  • pycryptodome==3.22.0
  • rsa>=4.9.1

2. MCP Client Configuration

Add the following configuration to your MCP client:

{
  "mcpServers": {
    "alipayplus-mcp": {
      "command": "uvx",
      "args": ["ant-intl-alipayplus-mcp"],
      "env": {
        "GATEWAY_URL": "https://open-sea-global.alipay.com",
        "CLIENT_ID": "your_client_id_here",
        "MERCHANT_PRIVATE_KEY": "your_merchant_private_key_here",
        "ALIPAY_PUBLIC_KEY": "your_alipay_public_key_here",
        "PAYMENT_NOTIFY_URL": "https://your-domain.com/payment/notify",
        "SETTLEMENT_CURRENCY": "USD",
        "MERCHANT_NAME": "Your Merchant Name",
        "MERCHANT_ID": "Your Merchant ID",
        "MERCHANT_MCC": "5411",
        "MERCHANT_REGION": "US"
      }
    }
  }
}

3. Environment Variables

Variable	Required	Description
GATEWAY_URL	❌	AlipayPlus API gateway URL (defaults to https://open-sea-global.alipay.com)
CLIENT_ID	✅	Merchant client ID for identity verification
MERCHANT_PRIVATE_KEY	✅	Merchant RSA private key for request signing
ALIPAY_PUBLIC_KEY	✅	Alipay RSA public key for response verification
PAYMENT_REDIRECT_URL	❌	URL to redirect after payment (defaults to empty string)
PAYMENT_NOTIFY_URL	❌	Payment result notification callback URL (defaults to http://localhost:8080/notify)
SETTLEMENT_CURRENCY	❌	Currency for settlement (defaults to empty string)
MERCHANT_NAME	❌	Merchant name (defaults to "Alipayplus MCP")
MERCHANT_ID	❌	Merchant ID (defaults to "M0000000001")
MERCHANT_MCC	❌	Merchant Category Code (defaults to "5411")
MERCHANT_REGION	❌	Merchant region code (defaults to "CN")

Integration Example

Here's how you can integrate the AlipayPlus MCP Server with your AI agent (using QwenAgent as an example):

import os
from qwen_agent.agents import Assistant

# Configure the MCP server as a tool
tools = [{
    "mcpServers": {
        "alipayplus-mcp": {
            "command": "uvx",
            "args": ["ant-intl-alipayplus-mcp"],
            "env": {
                "CLIENT_ID": os.getenv('CLIENT_ID'),
                "MERCHANT_PRIVATE_KEY": os.getenv('MERCHANT_PRIVATE_KEY'),
                "ALIPAY_PUBLIC_KEY": os.getenv('ALIPAY_PUBLIC_KEY'),
                "GATEWAY_URL": "https://open-sea-global.alipay.com",
                "PAYMENT_NOTIFY_URL": "https://your-domain.com/notify"
            }
        }
    }
}]

# Create your AI assistant with payment capabilities
bot = Assistant(
    llm={'model': 'qwen-max', 'api_key': 'your-api-key'},
    function_list=tools,
)

Changelog

See CHANGELOG.md for a detailed history of changes.

License

This project is licensed under the MIT License.

Acknowledgments

• Model Context Protocol for the standard
• AlipayPlus Integration for the AlipayPlus payment platform