# PayPls MCP Server
[](LICENSE)
[](https://www.npmjs.com/package/@paypls/mcp-server)
[](https://www.moltbook.com/post/23aa9fe6-21d0-48c7-86c7-fe45db58a08e)
MCP (Model Context Protocol) server that enables AI agents to manage Bitcoin and USDC payments through [PayPls](https://paypls.io).
> 🏆 **Built for the Circle USDC Hackathon 2026** — [View Submission](https://www.moltbook.com/post/23aa9fe6-21d0-48c7-86c7-fe45db58a08e)
## What is this?
> ⚠️ **Important:** This MCP server does NOT enforce spending limits or approval requirements.
> All limits are configured and enforced by the PayPls backend. Configure your limits in the
> [PayPls Dashboard](https://test.paypls.io) before giving agents access to real funds.
This server allows AI assistants like Claude to:
- 💰 Check wallet balances (BTC and USDC)
- 📤 Send payments with human approval
- 📥 Generate receive addresses
- 🔍 Track transaction status
All transactions can be configured to require human approval above certain thresholds, giving you control while enabling AI autonomy for small payments.
## Quick Links
| Resource | URL |
|----------|-----|
| 🌐 Landing Page | [paypls.io](https://paypls.io) |
| 🧪 Testnet Dashboard | [test.paypls.io](https://test.paypls.io) |
| 📡 API (Production) | [api.paypls.io](https://api.paypls.io) |
| 📖 Integration Guide | [paypls.io/SKILL.md](https://paypls.io/SKILL.md) |
| 🏆 Hackathon Submission | [Moltbook](https://www.moltbook.com/post/23aa9fe6-21d0-48c7-86c7-fe45db58a08e) |
| 💻 Source Code | [GitHub](https://github.com/n8m8/paypls-mcp) |
## Installation
```bash
npm install -g @paypls/mcp-server
```
Or run directly with npx:
```bash
npx @paypls/mcp-server
```
## Configuration
### 1. Get your API token
Sign up at [paypls.io](https://paypls.io) (or [test.paypls.io](https://test.paypls.io) for testnet) and generate an API token in Settings → API Keys.
### 2. Set environment variables
```bash
# Required: Your PayPls API token (starts with pp_)
PAYPLS_TOKEN=pp_your_token_here
# Optional: API URL (defaults to https://api.paypls.io)
# For testnet, use: https://paypls-api-dev.nfwalls.workers.dev
PAYPLS_API_URL=https://api.paypls.io
```
### 3. Configure Claude Desktop
Add to your Claude Desktop config file:
**macOS:** `~/Library/Application Support/Claude/claude_desktop_config.json`
**Windows:** `%APPDATA%\Claude\claude_desktop_config.json`
```json
{
"mcpServers": {
"paypls": {
"command": "npx",
"args": ["@paypls/mcp-server"],
"env": {
"PAYPLS_TOKEN": "pp_your_token_here"
}
}
}
}
```
Or if installed globally:
```json
{
"mcpServers": {
"paypls": {
"command": "paypls-mcp",
"env": {
"PAYPLS_TOKEN": "pp_your_token_here"
}
}
}
}
```
## Available Tools
| Tool | Description |
|------|-------------|
| `wallet_balance` | Check BTC or USDC balance of your wallet |
| `wallet_send_btc` | Send Bitcoin to an address |
| `wallet_send_usdc` | Send USDC to an EVM address |
| `wallet_receive` | Get an address to receive funds |
| `wallet_tx_status` | Check transaction status |
## Example Usage
Once configured, you can ask Claude things like:
- "What's my Bitcoin balance?"
- "Send 10,000 sats to tb1q... for the API subscription"
- "Send $25 USDC to 0x... for the design work"
- "Generate a receive address for my wallet"
- "Check the status of transaction abc-123"
## Security
- **Human approval**: Configure auto-approve limits in the PayPls dashboard. Transactions above the limit require explicit approval via Telegram.
- **Justifications**: Every send requires a justification that's logged and shown during approval.
- **Bucket isolation**: Use separate buckets to limit agent access to specific funds.
- **Token permissions**: API tokens can be scoped to specific buckets.
## Handling Approval Flows
When a transaction exceeds auto-approve limits, the API returns:
```json
{
"status": "pending_approval",
"transaction_id": "...",
"message": "Awaiting human approval via Telegram",
"expires_at": "2026-02-04T05:00:00Z"
}
```
Your agent should:
1. Inform the user that approval is needed
2. Optionally poll `wallet_tx_status` to check status
3. NOT retry the same transaction (use idempotency_key instead)
## Development
```bash
# Clone the repository
git clone https://github.com/n8m8/paypls-mcp.git
cd paypls-mcp
# Install dependencies
npm install
# Run in development mode
PAYPLS_TOKEN=pp_your_token npm run dev
# Build
npm run build
# Type check
npm run typecheck
```
## API Endpoints Used
This MCP server communicates with the PayPls Agent API:
| MCP Tool | API Endpoint |
|----------|--------------|
| `wallet_balance` | `GET /agent/balance` |
| `wallet_send_btc` | `POST /agent/send` |
| `wallet_send_usdc` | `POST /agent/send` |
| `wallet_receive` | `POST /agent/receive` |
| `wallet_tx_status` | `GET /agent/tx/:id` |
Full API documentation: [paypls.io/SKILL.md](https://paypls.io/SKILL.md)
## Environment Variables
| Variable | Required | Default | Description |
|----------|----------|---------|-------------|
| `PAYPLS_TOKEN` | Yes | - | Your PayPls API token (pp_xxx) |
| `PAYPLS_API_URL` | No | `https://api.paypls.io` | API endpoint URL |
## Testnet
Currently running on Bitcoin testnet (`tbtc`) and Ethereum Sepolia (USDC). Perfect for development and testing!
**Testnet API:** `https://paypls-api-dev.nfwalls.workers.dev`
**Testnet Dashboard:** [test.paypls.io](https://test.paypls.io)
## Support
- 📖 [Integration Guide](https://paypls.io/SKILL.md)
- 🐛 [Issues](https://github.com/n8m8/paypls-mcp/issues)
## License
[MIT](LICENSE)
---
<p align="center">
<sub>Built with ❤️ for the <a href="https://www.moltbook.com/post/23aa9fe6-21d0-48c7-86c7-fe45db58a08e">Circle USDC Hackathon 2026</a></sub>
</p>
