pix-mcp
Generates static Pix QR codes for payments using any Pix key, following EMV 4.0 standards and CRC16-CCITT validation.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@pix-mcp generate a static Pix QR code for R$150 to Maria in SΓ£o Paulo"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
Pix MCP Server v2.1.0
A lightweight Model Context Protocol (MCP) server that enables AI agents (Claude, Cursor, Windsurf) to generate static Pix QR codes via natural-language prompts.
π Features
π§ MCP Tool:
generateStaticPix- Generate static Pix QR codes for any Pix key (no API required)
π Production-ready: Comprehensive error handling and logging
π Type-safe: Full TypeScript implementation with Zod validation
π± QR Code generation: Automatic QR code creation for Pix payments
π¦ Zero Dependencies: No external API keys or services required
π Open & Accessible: Works without any registration or credentials
β EMV 4.0 Compliant: Follows BACEN PIX standards with proper CRC16-CCITT validation
Related MCP server: freeqrcode-mcp-server
π Quick Start
# Install globally
npm install -g pix-mcp
# Run in MCP mode (for Claude Desktop)
pix-mcp
# Run in HTTP mode (for web services)
MCP_MODE=http pix-mcpπ§ Usage
MCP Mode (Default)
# Start in MCP mode for Claude Desktop integration
pix-mcpHTTP Mode
# Start in HTTP mode on port 3000
MCP_MODE=http pix-mcpMaking Requests
HTTP API
curl -X POST http://localhost:3000/tools/call \
-H "Content-Type: application/json" \
-d '{
"name": "generateStaticPix",
"arguments": {
"pixKey": "10891990909",
"amount": 100.50,
"recipientName": "Franco Camelo Aguzzi",
"recipientCity": "Florianopolis"
}
}'MCP Tool
const result = await mcpClient.callTool('generateStaticPix', {
pixKey: '10891990909',
amount: 100.5,
recipientName: 'Franco Camelo Aguzzi',
recipientCity: 'Florianopolis',
});π Deployment
Railway
β οΈ Important: After deploying to Railway, add these environment variables in the Railway dashboard:
MCP_MODE=httpNODE_ENV=production(optional)
Manual Deployment
# Clone the repository
git clone https://github.com/Regenerating-World/pix-mcp.git
cd pix-mcp
# Install dependencies
npm install
# Build the project
npm run build
# Start the server in HTTP mode
MCP_MODE=http NODE_ENV=production node dist/index.jsπ License
MIT
π§ Configuration
Environment Variables
MCP_MODE: Server mode (stdiofor MCP,httpfor HTTP API) - Default:stdioNODE_ENV: Environment (development/production) - Default:developmentPORT: HTTP port when in HTTP mode - Default:3000
π€ Usage with AI Tools
Claude Desktop
Install the package globally:
npm install -g pix-mcpAdd to your Claude Desktop MCP configuration (
~/Library/Application Support/Claude/claude_desktop_config.jsonon macOS or%APPDATA%/Claude/claude_desktop_config.jsonon Windows):
{
"mcpServers": {
"pix-mcp": {
"command": "npx",
"args": ["pix-mcp"],
"env": {
"MCP_MODE": "stdio"
}
}
}
}Restart Claude Desktop and start using:
Create a Pix charge for R$25.50 to Maria Silva for lunchCursor (with MCP support)
Add to your Cursor MCP settings:
{
"mcpServers": {
"pix-mcp": {
"command": "pix-mcp"
}
}
}Windsurf (with MCP support)
Configure in Windsurf MCP settings:
{
"pix-mcp": {
"command": "npx pix-mcp",
"args": []
}
}Any MCP-compatible tool
Your tool should support MCP servers. Configure using:
Command:
npx pix-mcporpix-mcp(if installed globally)Protocol: stdio
Environment:
MCP_MODE=stdio
π¨ Available Tools
generateStaticPix
Creates a static Pix payment QR code following BACEN EMV 4.0 standards.
Parameters:
pixKey(string): Valid Pix key (email, phone, CPF, CNPJ, or random key)amount(number): Payment amount in BRL (0.01 to 999,999.99)recipientName(string): Name of the payment recipient (max 25 chars)recipientCity(string): City of the payment recipient (max 15 chars)
Returns:
Payment details (amount, recipient, city)
Pix copy-paste code (EMV format)
QR code image (base64 data URL)
Success status and message
Supported Pix Key Types:
π§ Email:
example@email.comπ± Phone:
+5511999999999π€ CPF:
12345678901(11 digits)π’ CNPJ:
12345678000195(14 digits)π Random Key:
123e4567-e89b-12d3-a456-426614174000(UUID format)
ποΈ Development
# Development mode with hot reload
npm run dev
# Run tests
npm test
# Build for production
npm run build
# Lint code
npm run lint
# Format code
npm run formatπΊοΈ Roadmap
Phase 1: MVP β
generateStaticPixtoolStatic Pix QR code generation
QR code generation
Claude Desktop compatibility
EMV 4.0 compliance
CRC16-CCITT validation
All Pix key types support
Public deployment
MCP server configuration files
Multi-tool compatibility
Phase 2: MCP Discovery
Register with MCP registry
Add to community MCP directories
Integration examples for more tools
π Security & Validation
β EMV 4.0 standard compliance
β CRC16-CCITT checksum validation
β Input validation with Zod schemas
β Pix key format validation
β Comprehensive error handling
β Type-safe TypeScript implementation
β οΈ Important Notes
CPF/CNPJ Keys: Must be valid and registered as Pix keys
Test Data: Avoid using fake CPFs like
12345678900- they will be rejected by banksStatic Codes: No expiration, recipient must check payments manually
Validation: All codes are EMV-compliant and pass bank validation
π License
MIT License - see LICENSE file for details.
π€ Contributing
Fork the repository
Create a feature branch
Make your changes
Add tests if applicable
Submit a pull request
π Support
GitHub Issues: Report bugs or request features
Documentation: Available in this README
Made with β€οΈ for the Brazilian Pix ecosystem
Available Tools
2 toolsgenerateStaticPixB
Generate a static Pix QR code for any Pix key (works without API credentials)
Inputs: pixKey (required), amount (required), recipientName (required), recipientCity (required).
healthCheckA
Check the health status of the Pix MCP server and providers
Inputs: no named parameters.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelogβ¦
TDQS
Scored across 2 tools
The two tools have completely distinct purposes: one generates a static Pix QR code, the other checks server health. No ambiguity or overlap exists.
Both tools use camelCase, but one starts with a verb (generateStaticPix) and the other with a noun (healthCheck). Minor inconsistency but still readable.
With only 2 tools, the server feels very thin for a Pix-related service, which typically includes dynamic Pix generation, key management, and administrative operations.
The server only covers static Pix generation and a health check, missing key functionality like dynamic Pix, Pix key validation, or transaction history, leading to significant gaps.
Related MCP Connectors
Generate QR codes for URLs, PIX, Wi-Fi, vCards, WhatsApp and more. For AI agents.
Brazil payments for AI agents β Pix, cards, boleto via Mercado Pago. Never holds funds.
Accept Pix in Brazil and settle in USDT/USDC; pay Pix with crypto; verify a Pix with no API key.
Argentina payments for AI agents β Mercado Pago wallet / cuotas via Mercado Pago. Never holds funds.
Related MCP Servers
- AlicenseAqualityFmaintenanceDynamic QR code platform for AI agents. Create, customize, and track QR codes without regenerating images. 37 tools covering 11 QR types (URL, vCard, WiFi, eventβ¦).373MIT
- AlicenseBqualityDmaintenanceEnables AI assistants to generate QR codes for URLs, text, vCard, WiFi, email, and phone numbers with customizable size, colors, and error correction.11MIT
- AlicenseNot gradedqualityDmaintenanceEnables AI agents to generate QR codes for URLs, WiFi, contacts, and more with structured parameters.4MIT
- AlicenseNot gradedqualityFmaintenanceEnables AI assistants to generate styled QR codes with customizable colors, styles, gradients, and frames, as well as typed QR codes for WiFi, vCard, etc., using the QRMint API without requiring an API key.1MIT