pinelabs-mcp-server

Pine Labs MCP Server

A Model Context Protocol (MCP) server for Pine Labs payment APIs. Connect your AI assistant — Claude Desktop, Cursor, VS Code, Windsurf, or any MCP-compatible client — to Pine Labs and manage payments, refunds, orders, payouts, settlements, and more through natural language.

Full Documentation · Available Tools · Use Cases · FAQs

Prerequisites

• Python 3.10+ — Download
• Pine Labs Client Credentials — Get your Client ID and Client Secret from the Pine Labs developer portal

Installation

pip install pinelabs-mcp-server

To verify the installation:

pinelabs-mcp-server --help

Quick Start

1. Set your credentials

Create a .env file in your working directory or export the variables directly:

export PINELABS_CLIENT_ID="your_client_id"
export PINELABS_CLIENT_SECRET="your_client_secret"
export PINELABS_ENV="uat"   # use "prod" for production

2. Start the server

pinelabs-mcp-server

The server starts on http://0.0.0.0:8000/mcp using Streamable HTTP transport by default.

3. Connect your AI client

Point your MCP-compatible AI client to the running server endpoint — see AI Client Configuration below.

AI Client Configuration

Add the following to your AI client's MCP configuration file:

Claude Desktop

File: claude_desktop_config.json

{
  "mcpServers": {
    "pinelabs": {
      "url": "http://localhost:8000/mcp",
      "headers": {
        "X-Client-Id": "your_client_id",
        "X-Client-Secret": "your_client_secret"
      }
    }
  }
}

Cursor

File: ~/.cursor/mcp.json

{
  "mcpServers": {
    "pinelabs": {
      "url": "http://localhost:8000/mcp",
      "headers": {
        "X-Client-Id": "your_client_id",
        "X-Client-Secret": "your_client_secret"
      }
    }
  }
}

VS Code

File: .vscode/mcp.json (in your project root)

{
  "servers": {
    "pinelabs": {
      "url": "http://localhost:8000/mcp",
      "headers": {
        "X-Client-Id": "your_client_id",
        "X-Client-Secret": "your_client_secret"
      }
    }
  }
}

Note: VS Code uses "servers" instead of "mcpServers" as the top-level key.

Environment Variables

Variable	Required	Default	Description
PINELABS_CLIENT_ID	Yes	—	Your Pine Labs client ID
PINELABS_CLIENT_SECRET	Yes	—	Your Pine Labs client secret
PINELABS_ENV	No	uat	Environment: uat or prod
URL
PINELABS_TOKEN_URL	No	Auto from env	Override the token endpoint URL
HOST	No	0.0.0.0	Server bind address
PORT	No	8000	Server port
LOG_LEVEL	No	INFO	Logging level (DEBUG, INFO, WARNING, ERROR)
LOG_FORMAT	No	text	Log format: text or json
TOOLS	No	—	Comma-separated tool filter (see below)
REDIS_HOST	No	localhost	Redis host for token caching
REDIS_PORT	No	6379	Redis port
REDIS_DB	No	0	Redis database index

Available Tools

The server exposes 56 tools across these categories:

Category	Examples
Payment Links	Create, retrieve, cancel, and resend payment links
Orders	Create, track, and manage checkout orders
Refunds	Create and retrieve refund details
Payouts	Initiate and track payouts
Settlements	Query settlement details and cancel settlements
Subscriptions	Create and manage recurring subscriptions
Card Payments	Server-to-server card payment flows with OTP
UPI / QR	Generate QR codes for UPI intent payments
API Docs	Search Pine Labs API documentation
Code Generation	Generate integration code snippets

See the complete tools reference for details.

Tool Filtering

You can control which tools the server exposes using the TOOLS environment variable. Tools are classified by operation (read / write / destructive) and category (e.g., payment_links, orders, refunds). Use a comma-separated mix of operation types and domain categories:

# Only read tools
TOOLS=read pinelabs-mcp-server

# Only payment link tools
TOOLS=payment_links pinelabs-mcp-server

# Read + write tools (excludes destructive)
TOOLS="read,write" pinelabs-mcp-server

# Read tools for orders and payment_links only
TOOLS="read,orders,payment_links" pinelabs-mcp-server

Short aliases are supported:

Alias	Expands To
payment	payment_links
order	orders
refund	refunds
payout	payouts
settlement	settlements
subscription	subscriptions

Running with Docker

docker build -t pinelabs-mcp-server .

docker run -p 8000:8000 \
  -e PINELABS_CLIENT_ID="your_client_id" \
  -e PINELABS_CLIENT_SECRET="your_client_secret" \
  -e PINELABS_ENV="uat" \
  pinelabs-mcp-server

Development

# Clone the repository
git clone https://github.com/Plural-Pvt/pinelabs-mcp-server.git
cd pinelabs-mcp-server

# Install dependencies
pip install -r requirements.txt
pip install -r requirements-test.txt  # for running tests

# Run the server locally
python main.py

# Run tests
pytest

Troubleshooting

Issue	Fix
pinelabs-mcp-server command not found	Ensure pip install pinelabs-mcp-server completed successfully and the install directory is in your PATH
Authentication errors	Verify your PINELABS_CLIENT_ID and PINELABS_CLIENT_SECRET are correct
Tools not appearing in AI client	Restart your AI assistant after configuring the MCP endpoint; check server logs for errors
Connection refused	Ensure the server is running (pinelabs-mcp-server) and the port matches your client config
Redis connection errors	Redis is optional for local dev — the server falls back to in-memory token caching

Also Available on npm

If you prefer a Node.js-based setup with automatic AI client configuration, use the npm package instead:

npx pinelabs-mcp configure --client-id=YOUR_ID --client-secret=YOUR_SECRET
npx pinelabs-mcp setup cursor   # or: claude-desktop, vscode, windsurf

See pinelabs-mcp on npm for details.

License

MIT — see LICENSE for details.