MCP-Server

MCP Server (deprecated)

A Model Context Protocol (MCP) server that provides comprehensive integration with PayPal's APIs. This server enables seamless interaction with PayPal's payment processing, invoicing, subscription management, and business operations through a standardized interface.

Features

Payment Processing

• Orders Management: Create, update, and track orders
• Payment Processing: Process payments with various methods
• Payment Tokens: Create and manage payment tokens for future use
• Dispute Management: Handle payment disputes and resolutions

Business Operations

• Product Management: Create and manage product catalogs
• Invoicing: Generate and send professional invoices
• Payouts: Process batch payouts to multiple recipients
• Subscription Management: Create and manage recurring billing

User Management

• Identity Verification: Verify user identities
• User Information: Retrieve and manage user data
• Web Profile Management: Customize checkout experiences

Architecture

graph TB
    subgraph "MCP Environment"
        Client[MCP Client]
        Server[PayPal MCP Server]
        Validation[Input Validation]
        Auth[OAuth Authentication]
        Cache[Token Cache]
        ErrorHandler[Error Handler]
    end

    subgraph "PayPal APIs"
        Orders[Orders API]
        Payments[Payments API]
        Payouts[Payouts API]
        Invoicing[Invoicing API]
        Products[Products API]
        Subscriptions[Subscriptions API]
        Disputes[Disputes API]
        Identity[Identity API]
    end

    Client --> |Request| Server
    Server --> |Response| Client
    Server --> Validation
    Server --> Auth
    Auth --> Cache
    Auth --> |Access Token| PayPal
    Server --> ErrorHandler

    Server --> Orders
    Server --> Payments
    Server --> Payouts
    Server --> Invoicing
    Server --> Products
    Server --> Subscriptions
    Server --> Disputes
    Server --> Identity

    style Client fill:#f9f,stroke:#333,stroke-width:2px
    style Server fill:#bbf,stroke:#333,stroke-width:2px
    style Auth fill:#bfb,stroke:#333,stroke-width:2px
    style Validation fill:#bfb,stroke:#333,stroke-width:2px
    style Cache fill:#fbb,stroke:#333,stroke-width:2px
    style ErrorHandler fill:#fbb,stroke:#333,stroke-width:2px

Installation

Prerequisites

• Node.js 16.x or later
• PayPal Developer Account with API credentials

Manual Installation

1. Clone the repository

   git clone https://github.com/arbuthnot-eth/PayPal-MCP.git
   cd PayPal-MCP
   

2. Install dependencies

   npm install
   

3. Build the project

   npm run build
   

4. Configure PayPal credentials in your MCP settings file:

   {
     "mcpServers": {
       "paypal": {
         "command": "node",
         "args": ["path/to/paypal-mcp/build/index.js"],
         "env": {
           "PAYPAL_CLIENT_ID": "your_client_id",
           "PAYPAL_CLIENT_SECRET": "your_client_secret",
           "PAYPAL_ENVIRONMENT": "sandbox" // or "live"
         },
         "disabled": false,
         "autoApprove": []
       }
     }
   }
   

Available Tools

Payment Operations

create_payment_token

Create a payment token for future use.

{
  customer: {
    id: string;
    email_address?: string;
  };
  payment_source: {
    card?: {
      name: string;
      number: string;
      expiry: string;
      security_code: string;
    };
    paypal?: {
      email_address: string;
    };
  };
}

create_order

Create a new order in PayPal.

{
  intent: 'CAPTURE' | 'AUTHORIZE';
  purchase_units: Array<{
    amount: {
      currency_code: string;
      value: string;
    };
    description?: string;
    reference_id?: string;
    items?: Array<{
      name: string;
      quantity: string;
      unit_amount: {
        currency_code: string;
        value: string;
      };
    }>;
  }>;
  application_context?: {
    brand_name?: string;
    shipping_preference?: 'GET_FROM_FILE' | 'NO_SHIPPING' | 'SET_PROVIDED_ADDRESS';
    user_action?: 'CONTINUE' | 'PAY_NOW';
  };
}

capture_order

Capture payment for an authorized order.

{
  order_id: string;
  payment_source?: {
    token?: {
      id: string;
      type: string;
    };
  };
}

create_subscription

Create a subscription for recurring billing.

{
  plan_id: string;
  subscriber: {
    name: {
      given_name: string;
      surname: string;
    };
    email_address: string;
  };
  application_context?: {
    brand_name?: string;
    shipping_preference?: 'GET_FROM_FILE' | 'NO_SHIPPING' | 'SET_PROVIDED_ADDRESS';
    user_action?: 'CONTINUE' | 'SUBSCRIBE_NOW';
    payment_method?: {
      payer_selected?: string;
      payee_preferred?: string;
    };
  };
}

Business Operations

create_product

Create a new product in the catalog.

{
  name: string;
  description: string;
  type: 'PHYSICAL' | 'DIGITAL' | 'SERVICE';
  category: string;
  image_url?: string;
  home_url?: string;
}

create_invoice

Generate a new invoice.

{
  invoice_number: string;
  reference: string;
  currency_code: string;
  recipient_email: string;
  items: Array<{
    name: string;
    quantity: string;
    unit_amount: {
      currency_code: string;
      value: string;
    };
    description?: string;
    tax?: {
      name: string;
      percent: string;
    };
  }>;
  note?: string;
  terms_and_conditions?: string;
  memo?: string;
  payment_term?: {
    term_type: 'DUE_ON_RECEIPT' | 'DUE_ON_DATE' | 'NET_10' | 'NET_15' | 'NET_30' | 'NET_45' | 'NET_60' | 'NET_90';
    due_date?: string;
  };
}

create_payout

Process a batch payout.

{
  sender_batch_header: {
    sender_batch_id: string;
    email_subject?: string;
    recipient_type?: string;
  };
  items: Array<{
    recipient_type: string;
    amount: {
      value: string;
      currency: string;
    };
    receiver: string;
    note?: string;
  }>;
}

Error Handling

The server implements comprehensive error handling:

• Input Validation: Detailed validation errors with specific messages
• PayPal API Errors: Structured error responses with PayPal error details
• Network Errors: Retry logic for transient network issues
• Authentication Errors: Automatic token refresh and clear error messages
• Rate Limiting: Backoff strategies for API rate limits

Security Considerations

• All sensitive data is validated and sanitized
• OAuth 2.0 authentication with PayPal
• Secure credential management through environment variables
• Input validation for all API parameters
• Error messages don't expose sensitive information

Development

Building

npm run build

Running in Development Mode

npm run dev

Testing

npm test

Linting

npm run lint

Formatting

npm run format

Contributing

1. Fork the repository
2. Create a feature branch
3. Commit your changes
4. Push to the branch
5. Create a Pull Request

License

MIT License