PayPal MCP Server

Created By

arbuthnot-eth9 months ago

A Model Context Protocol (MCP) server for PayPal API integration with improved error handling, comprehensive API coverage, and detailed documentation.

# paypal

# api-integration

Overview Content Tools Comments

Content

PayPal MCP Server

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

Clone the repository

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

Install dependencies
```
npm install
```
Build the project
```
npm run build
```

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;
  }>;
}