Pinelabs Mcp Server

Pine Labs Payment Gateway MCP Server（官方）

Pine Labs 支付网关的 MCP 客户端——使用您的客户端凭据，将 Claude Desktop、Cursor、VS Code 和其他 AI 助手连接到 Pine Labs 支付 API。

完整文档 | 可用工具 | 使用场景 | 常见问题

---

目录

• 前提条件
• 快速开始
• CLI 命令
• 支持的 AI 客户端
• 手动配置
• 可用工具
• 使用场景
• 远程 MCP 服务
• 身份验证
• 本地 MCP 服务
• 配置
• 调试
• 常见问题
• 关键词
• 许可证

---

前提条件

• Node.js 18+ —— 下载 或安装 npm i pinelabs-mcp
• Pine Labs 客户端凭据 —— 从 Pine Labs 开发者门户获取您的 Client ID 和 Client Secret

---

快速开始

获取凭据

1. 使用账户提供的信息，在 Pine Labs 商户控制面板注册或登录。
2. 前往账户设置，查找您的 Client ID 和 Client Secret。
3. 按照上述设置说明，在 MCP 服务配置中使用这些凭据。

配置并连接

# 1. Configure your credentials
npx pinelabs-mcp configure --client-id=YOUR_ID --client-secret=YOUR_SECRET

# 2. Test your connection
npx pinelabs-mcp test

# 3. Auto-configure your AI client
npx pinelabs-mcp setup cursor       # or: claude-desktop, vscode, windsurf, opencode, copilot, codex

然后重启 AI 客户端，即可开始使用 Pine Labs 工具。

---

CLI 命令

pinelabs-mcp start                             Start MCP server (stdio mode)
pinelabs-mcp configure                         Interactive credential setup
pinelabs-mcp configure --client-id=X --client-secret=Y [--env=uat|prod]
pinelabs-mcp test                              Test connectivity and credentials
pinelabs-mcp setup <client>                    Auto-configure an AI client
pinelabs-mcp setup <client> --local            Use local path (dev mode)
pinelabs-mcp setup <client> --print            Preview config without writing
pinelabs-mcp status                            Show current configuration
pinelabs-mcp help                              Show help message
pinelabs-mcp --version                         Show version

---

支持的 AI 客户端

客户端	命令	配置路径
Claude Desktop	setup claude-desktop	特定平台的 Claude 配置
Cursor	setup cursor	~/.cursor/mcp.json
VS Code	setup vscode	.vscode/mcp.json（项目）
Windsurf	setup windsurf	~/.codeium/windsurf/mcp_config.json
OpenCode	setup opencode	.opencode/config.json（项目）
GitHub Copilot	setup copilot	~/.copilot/mcp-config.json
OpenAI Codex	setup codex	.codex/config.toml

---

手动配置

如果您希望手动配置，而不是使用 npx pinelabs-mcp setup，请将以下内容添加到 AI 客户端的 MCP 配置中：

{
  "mcpServers": {
    "pinelabs": {
      "command": "npx",
      "args": ["-y", "pinelabs-mcp"],
      "env": {
        "PINELABS_CLIENT_ID": "your_client_id",
        "PINELABS_CLIENT_SECRET": "your_client_secret"
      }
    }
  }
}

注意： VS Code 使用 "servers" 而不是 "mcpServers" 作为顶层键。在生产环境中，请在 env 块中添加 "PINELABS_ENV": "prod"。

---

可用工具

Pine Labs MCP 服务提供多个类别的 50 多种工具。每种工具都对应一个特定的 Pine Labs 支付 API 端点。

工具类型说明

下方每种工具都标注了一个 类型，用于说明其访问模式和操作风险。这有助于您判断哪些工具适合在只读部署中安全使用，以及哪些工具在自主（Agent）工作流中需要明确的用户确认。

类型	含义	示例
Read	安全且无副作用。仅获取或查询数据。可在只读模式下使用。	get_order_by_order_id、get_all_settlements、list_plural_apis
Write	创建或修改资源。不会造成破坏，但会更改服务状态。只读模式下会跳过。	create_payment_link、create_order、update_plan
Destructive	取消、删除、退款或转移资金。不可逆或会产生财务影响。在 Agent 工作流中应要求用户明确确认。	cancel_order、create_refund、create_payout、delete_plan

只读模式： 使用 --read-only 运行服务（或设置等效配置），仅注册 Read 工具，并跳过所有 Write / Destructive 工具集。适用于分析、监控或不可信的 Agent 场景。

付款链接

工具	类型	描述	API 参考
create_payment_link	写入	创建新的付款链接以收款	付款链接 - 创建
get_payment_link_by_id	读取	根据付款链接 ID 获取付款链接	付款链接 - 按 ID 获取
get_payment_link_by_merchant_reference	读取	根据商户付款链接引用获取付款链接	付款链接 - 按引用获取
cancel_payment_link	破坏性操作	取消有效的付款链接	付款链接 - 取消
resend_payment_link_notification	写入	向客户重新发送付款链接通知	付款链接 - 重新发送

订单

工具	类型	描述	API 参考
get_order_by_order_id	读取	根据订单 ID 获取订单详情	订单 - 按 ID 获取
get_order_by_merchant_order_reference	读取	根据商户订单引用获取订单详情	订单 - 按商户引用获取
capture_order	写入	扣取订单中此前已授权的款项	订单 - 扣款
cancel_order	破坏性操作	取消订单中预先授权的款项	订单 - 取消
fetch_order_payments	读取	获取与订单关联的所有付款尝试	订单 - 获取付款记录

结账订单

工具	类型	描述	API 参考
create_order	写入	创建新的结账订单并生成结账链接	订单 - 创建

银行卡付款

工具	类型	描述	API 参考
create_card_payment	写入	针对订单创建服务器到服务器的银行卡付款	银行卡付款 - 创建
get_card_details	读取	获取银行卡号对应的卡片详情（BIN、网络、类型）	卡片详情 - 获取

OTP

工具	类型	描述	API 参考
generate_otp	写入	为银行卡付款身份验证流程生成 OTP	OTP - 生成
submit_otp	写入	提交 OTP 以完成银行卡付款身份验证	OTP - 提交
resend_otp	写入	为银行卡付款身份验证重新发送 OTP	OTP - 重新发送

退款

工具	类型	描述	API 参考
create_refund	破坏性操作	对已扣款项发起全额或部分退款	退款 - 创建

结算

工具	类型	描述	API 参考
get_all_settlements	读取	检索商户在指定日期范围内的所有结算	结算 - 获取全部
get_settlement_by_utr	读取	根据 UTR（唯一交易参考号）检索指定结算	结算 - 按 UTR 获取

付款

工具	类型	描述	API 参考
create_payout	破坏性操作	创建付款，将资金拨付给受益人（会转移资金）	付款 - 创建
get_payout_details	读取	根据付款 ID 检索付款详情	付款 - 获取
get_payout_payments	读取	列出与某笔付款关联的支付	付款 - 获取支付
get_payout_balance	读取	检索商户可用的付款余额	付款 - 获取余额
update_payout	写入	更新现有付款请求	付款 - 更新
cancel_payout	破坏性操作	取消待处理的付款请求	付款 - 取消

订阅

工具	类型	描述	API 参考
create_plan	写入	创建新的订阅计划	计划 - 创建
get_plans	读取	获取订阅计划	计划 - 获取全部
get_plan_by_id	读取	根据计划 ID 获取订阅计划	计划 - 获取指定项
get_plan_by_merchant_reference	读取	根据商户计划引用获取计划	计划 - 获取指定项
update_plan	写入	更新现有订阅计划	计划 - 更新
delete_plan	破坏性操作	删除订阅计划	计划 - 删除
create_subscription	写入	根据计划创建新的订阅	订阅 - 创建
get_subscriptions	读取	获取订阅	订阅 - 获取全部
get_subscription_by_id	读取	根据订阅 ID 获取订阅	订阅 - 获取指定项
get_subscription_by_merchant_reference	读取	根据商户引用获取订阅	订阅 - 获取指定项
pause_subscription	写入	暂停有效订阅	订阅 - 暂停
resume_subscription	写入	恢复已暂停的订阅	订阅 - 恢复
cancel_subscription	破坏性操作	取消有效订阅	订阅 - 取消
update_subscription	写入	更新现有订阅	订阅 - 更新
create_presentation	写入	为订阅创建付款请求	付款请求 - 创建
get_presentation	读取	根据付款请求 ID 获取付款请求	付款请求 - 获取
delete_presentation	破坏性操作	删除付款请求	付款请求 - 删除
get_presentations_by_subscription_id	读取	获取某个订阅的所有付款请求	付款请求 - 按订阅获取
get_presentation_by_merchant_reference	读取	根据商户引用获取付款请求	付款请求 - 获取
send_subscription_notification	写入	发送订阅的扣款前通知	付款请求 - 创建
create_debit	破坏性操作	对订阅执行扣款（收取款项）	付款请求 - 创建
create_merchant_retry	写入	重试执行扣款失败的授权（最多重试 3 次）	商户重试

UPI 支付

工具	类型	说明	API 参考
create_upi_intent_payment_with_qr	写入	创建带二维码的 UPI 意向支付，以便即时收款	UPI 意向二维码

报告和交易搜索

工具	类型	说明	API 参考
get_payment_link_details	读取	获取指定日期范围内的支付链接详情	API 文档
get_order_details	读取	获取指定日期范围内的订单详情	API 文档
get_refund_order_details	读取	获取指定日期范围内的退款订单详情	API 文档
search_transaction	读取	通过交易 ID 搜索交易	API 文档

开发者工具

工具	类型	说明
get_api_documentation	读取	获取指定 API 的 Pine Labs API 文档
list_plural_apis	读取	列出所有可用的 Pine Labs (Plural) API 及其说明
detect_stack	读取	检测当前项目的技术栈，以便提供适配的集成指南
integrate_pinelabs_checkout	读取	生成适配技术栈的代码片段和 Pine Labs Checkout 集成指南

商户分析

工具	类型	说明
get_merchant_success_rate	读取	获取商户在指定日期范围内的交易成功率

---

使用场景

• 支付网关集成：将 AI 应用连接到 Pine Labs 支付网关，以便以编程方式创建结账订单、生成支付链接和处理交易。
• AI 驱动的结账流程：构建对话式结账体验，让 AI 助手创建订单、生成支付链接并实时跟踪支付状态。
• UPI 支付自动化：通过 AI 驱动的界面生成 UPI 意向二维码并处理 UPI 支付，用于应用内或销售点收款。
• 订阅生命周期管理：自动创建定期支付计划、激活订阅、暂停／恢复周期、发起扣款以及发送扣款前通知。
• Agent 式支付工作流：构建自主 AI Agent，无需人工干预即可管理端到端支付操作——从创建订单到对账。
• 订单跟踪和对账：查询订单详情、按 ID 搜索交易并核对支付，以验证状态和解决争议。
• 支付分析和报告：按自定义日期范围获取支付链接报告、订单摘要、退款详情和商户成功率。
• 客户支持自动化：让支持人员或聊天机器人能够查询交易、查看支付状态、取消订单并重新发送支付通知。

---

远程 MCP 服务

远程 MCP 服务由 Pine Labs 托管和维护。如果你更希望手动使用远程端点配置 AI 客户端，而不是使用 npm CLI，请采用此方式。

优势

• 零设置：无需管理 Python、Docker 或本地基础设施
• 始终保持更新：自动获取最新支付 API 功能和安全补丁
• 高可用性：托管在 Pine Labs 生产基础设施上
• 安全身份验证：通过 HTTPS 使用客户端凭据进行身份验证

如果你连接的是可自托管的远程部署，而不是 Pine Labs 托管的服务，请将下方的远程 URL 替换为 <your-mcp-server-url>。

先决条件

代理远程 MCP 连接需要 npx。 请安装 Node.js（其中包含 npm 和 npx）：

macOS

brew install node

Windows

choco install nodejs

或者从 https://nodejs.org/ 下载。

验证安装

npx --version

在 Cursor 中使用

将以下内容添加到 Cursor MCP 设置中：

{
  "mcpServers": {
    "pinelabs": {
      "command": "npx",
      "args": [
        "mcp-remote",
        "https://mcp.pinelabs.com/mcp",
        "--header",
        "X-Client-Id:<your-client-id>",
        "--header",
        "X-Client-Secret:<your-client-secret>"
      ]
    }
  }
}

将 <your-client-id> 和 <your-client-secret> 替换为你的 Pine Labs 凭据。详情请参阅身份验证。

在 Claude Desktop 中使用

将以下内容添加到你的 claude_desktop_config.json：

{
  "mcpServers": {
    "pinelabs": {
      "command": "npx",
      "args": [
        "mcp-remote",
        "https://mcp.pinelabs.com/mcp",
        "--header",
        "X-Client-Id:<your-client-id>",
        "--header",
        "X-Client-Secret:<your-client-secret>"
      ]
    }
  }
}

将 <your-client-id> 和 <your-client-secret> 替换为你的 Pine Labs 凭据。

• 在 Claude Desktop 中配置 MCP 服务：MCP 快速入门指南
• 安装 Claude Desktop：下载

在 VS Code 中使用

将以下内容添加到 VS Code 设置（JSON）中：

{
  "mcp": {
    "inputs": [
      {
        "type": "promptString",
        "id": "pinelabs_client_id",
        "description": "Pine Labs Client ID"
      },
      {
        "type": "promptString",
        "id": "pinelabs_client_secret",
        "description": "Pine Labs Client Secret",
        "password": true
      }
    ],
    "servers": {
      "pinelabs": {
        "command": "npx",
        "args": [
          "mcp-remote",
          "https://mcp.pinelabs.com/mcp",
          "--header",
          "X-Client-Id:${input:pinelabs_client_id}",
          "--header",
          "X-Client-Secret:${input:pinelabs_client_secret}"
        ]
      }
    }
  }
}

在 VS Code 的 Agent 模式文档中了解有关 MCP 服务的更多信息。

---

身份验证

MCP 服务使用 Pine Labs 颁发的 Client ID 和 Client Secret 凭据进行身份验证。

注意： 对于本地部署，可以通过 CLI 参数或环境变量传递凭据。对于远程服务，凭据通过 HTTP 标头传递。

---

本地 MCP 服务

在你自己的基础设施上部署 MCP 服务，以全面掌控运行时环境。

前提条件

• Python 3.12+
• Docker（可选，用于容器化部署）
• Git

在 Windows 上安装（Chocolatey）

在 Windows 计算机上获取 MCP 服务最快捷的方式是使用 Chocolatey。该软件包是一个轻量级封装程序，会将 Python 3.10+ 作为依赖项安装，然后从 PyPI 安装 pinelabs-mcp-server，并在 PATH 上注册 pinelabs-mcp 启动脚本。

choco install pinelabs-mcp

验证安装：

pinelabs-mcp --help

通过 stdio 运行服务：

pinelabs-mcp stdio --client-id <your-client-id> --client-secret <your-client-secret> --env uat

MCP 客户端配置（Claude Desktop / Cursor / VS Code）

运行 choco install 后，将 MCP 客户端指向 pinelabs-mcp 启动脚本：

{
  "mcpServers": {
    "pinelabs": {
      "command": "pinelabs-mcp",
      "args": ["stdio", "--env", "uat"],
      "env": {
        "PINELABS_CLIENT_ID": "<your-client-id>",
        "PINELABS_CLIENT_SECRET": "<your-client-secret>"
      }
    }
  }
}

卸载：

choco uninstall pinelabs-mcp

使用公共 Docker 镜像（推荐）

直接使用 Pine Labs 官方 Docker 镜像。无需构建。

注意： 若要固定特定版本，请在以下配置中将 pinelabs/mcp:latest 替换为 pinelabs/mcp:<version-tag>（例如，pinelabs/mcp:v1.0.0）。

在 Claude Desktop 中使用

将以下内容添加到你的 claude_desktop_config.json：

{
  "mcpServers": {
    "pinelabs": {
      "command": "docker",
      "args": [
        "run",
        "--rm",
        "-i",
        "-e",
        "PINELABS_CLIENT_ID",
        "-e",
        "PINELABS_CLIENT_SECRET",
        "-e",
        "PINELABS_ENV",
        "pinelabs/mcp:latest"
      ],
      "env": {
        "PINELABS_CLIENT_ID": "<your-client-id>",
        "PINELABS_CLIENT_SECRET": "<your-client-secret>",
        "PINELABS_ENV": "prod"
      }
    }
  }
}

将 <your-client-id> 和 <your-client-secret> 替换为你的 Pine Labs 凭据。

• 在 Claude Desktop 中配置 MCP 服务：MCP 快速入门指南
• 安装 Claude Desktop：下载

在 VS Code 中使用

将以下内容添加到 VS Code 设置（JSON）中：

{
  "mcp": {
    "inputs": [
      {
        "type": "promptString",
        "id": "pinelabs_client_id",
        "description": "Pine Labs Client ID"
      },
      {
        "type": "promptString",
        "id": "pinelabs_client_secret",
        "description": "Pine Labs Client Secret",
        "password": true
      }
    ],
    "servers": {
      "pinelabs": {
        "command": "docker",
        "args": [
          "run",
          "--rm",
          "-i",
          "-e",
          "PINELABS_CLIENT_ID",
          "-e",
          "PINELABS_CLIENT_SECRET",
          "-e",
          "PINELABS_ENV=prod",
          "pinelabs/mcp:latest"
        ],
        "env": {
          "PINELABS_CLIENT_ID": "${input:pinelabs_client_id}",
          "PINELABS_CLIENT_SECRET": "${input:pinelabs_client_secret}"
        }
      }
    }
  }
}

在 VS Code 的 Agent 模式文档中了解有关 MCP 服务的更多信息。

在 Cursor 中使用

{
  "mcpServers": {
    "pinelabs": {
      "command": "docker",
      "args": [
        "run",
        "--rm",
        "-i",
        "-e",
        "PINELABS_CLIENT_ID",
        "-e",
        "PINELABS_CLIENT_SECRET",
        "-e",
        "PINELABS_ENV=prod",
        "pinelabs/mcp:latest"
      ],
      "env": {
        "PINELABS_CLIENT_ID": "<your-client-id>",
        "PINELABS_CLIENT_SECRET": "<your-client-secret>"
      }
    }
  }
}

将 <your-client-id> 和 <your-client-secret> 替换为你的 Pine Labs 凭据。

从 Docker 构建（替代方式）

克隆代码库并在本地构建 Docker 镜像：

git clone https://github.com/plural-pinelabs/pinelabs-online-mcp.git
cd pinelabs-online-mcp
docker build -t pinelabs-mcp-server:latest .

构建完成后，在上述配置中将 pinelabs/mcp:latest 替换为 pinelabs-mcp-server:latest。

从源代码构建

无需 Docker，直接从源代码运行服务：

# Clone the repository
git clone https://github.com/plural-pinelabs/pinelabs-online-mcp.git
cd pinelabs-online-mcp

# Create and activate a virtual environment
python -m venv .venv
source .venv/bin/activate      # macOS/Linux
# .venv\Scripts\activate       # Windows

# Install dependencies
pip install -r requirements.txt

# Run the server (stdio mode)
python -m cli.pinelabs_mcp_server.main stdio \
  --client-id <your-client-id> \
  --client-secret <your-client-secret> \
  --env prod

服务运行后，配置 MCP 客户端以连接到本地进程。以下是 VS Code 示例：

{
  "mcp": {
    "servers": {
      "pinelabs": {
        "command": "python",
        "args": [
          "-m",
          "cli.pinelabs_mcp_server.main",
          "stdio"
        ],
        "env": {
          "PINELABS_CLIENT_ID": "<your-client-id>",
          "PINELABS_CLIENT_SECRET": "<your-client-secret>",
          "PINELABS_ENV": "prod"
        }
      }
    }
  }
}

---

配置

环境变量

变量	必填	默认值	描述
PINELABS_CLIENT_ID	是	--	用于 API 身份验证的 Pine Labs 客户端 ID
PINELABS_CLIENT_SECRET	是	--	用于 API 身份验证的 Pine Labs 客户端密钥
PINELABS_ENV	否	uat	目标环境：uat 或 prod
LOG_LEVEL	否	INFO	日志详细程度：DEBUG、INFO、WARNING、ERROR
LOG_FILE	否	stderr	日志输出文件路径
READ_ONLY	否	false	限制为只读工具（禁用写入操作）
TOOLSETS	否	all	要启用的工具集列表，以逗号分隔

命令行标志

python -m cli.pinelabs_mcp_server.main <transport> [options]

Transports:
  stdio                 Standard I/O transport (for MCP clients)
  http                  HTTP transport (for web-based access)

Options:
  --client-id           Pine Labs client ID
  --client-secret       Pine Labs client secret
  --env                 Environment: uat, prod (default: uat)
  --log-file            Path to log file
  --log-level           Log level: DEBUG, INFO, WARNING, ERROR
  --read-only           Only register read-only tools
  --toolsets            Comma-separated list of toolsets to enable

HTTP-only options:
  --host                Host to bind to (default: 0.0.0.0)
  --port                Port to listen on (default: 8000)

---

调试服务

使用 --log-level DEBUG 标志，并可选使用 --log-file 写入详细日志以进行故障排查：

python -m cli.pinelabs_mcp_server.main stdio \
  --client-id <ID> --client-secret <SECRET> \
  --log-level DEBUG --log-file ./debug.log

---

常见问题

问：金额需要以派沙（paisa）为单位提供吗？ 答：不需要。金额以卢比为单位指定（例如，500 表示 500 印度卢比）。无需转换为派沙。

问：支持哪些环境？ 答：服务支持 uat（默认）和 prod 环境。通过 PINELABS_ENV 或 --env 设置。

问：可以限制可用工具吗？ 答：可以。使用 --read-only 标志禁用写入操作，或使用 --toolsets 启用特定工具集（例如，--toolsets payment_links,orders）。

问：在哪里可以找到完整的 API 参考？ 答：请访问 Pine Labs 开发者文档，查看完整的 API 参考。

---

关键词

Pine Labs、Pine Labs Online、Plural、Plural Online、支付网关、在线支付网关、结账网关、支付结账、在线结账、托管结账、支付页面、支付、在线支付、数字支付、支付处理、接受付款、收款、支付集成、网关集成、支付 API、支付 API、结账 API、网关 API、UPI、银行卡、信用卡、借记卡、网上银行、电子钱包、EMI、无卡 EMI、订阅、周期性付款、订单、订单付款、创建付款、发起付款、处理付款、支付链接、MCP 服务、Model Context Protocol、AI 支付自动化、智能体支付、二维码支付、支付编排、商户 API、交易报告、金融科技、SDK

---

许可证

本项目采用 Apache 2.0 许可证授权。完整条款请参见 LICENSE。