Skip to main content
Glama

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-mcp

HTTP Mode

# Start in HTTP mode on port 3000
MCP_MODE=http pix-mcp

Making 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

Deploy on Railway

⚠️ Important: After deploying to Railway, add these environment variables in the Railway dashboard:

  • MCP_MODE=http

  • NODE_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 (stdio for MCP, http for HTTP API) - Default: stdio

  • NODE_ENV: Environment (development/production) - Default: development

  • PORT: HTTP port when in HTTP mode - Default: 3000

πŸ€– Usage with AI Tools

Claude Desktop

  1. Install the package globally:

npm install -g pix-mcp
  1. Add to your Claude Desktop MCP configuration (~/Library/Application Support/Claude/claude_desktop_config.json on macOS or %APPDATA%/Claude/claude_desktop_config.json on Windows):

{
  "mcpServers": {
    "pix-mcp": {
      "command": "npx",
      "args": ["pix-mcp"],
      "env": {
        "MCP_MODE": "stdio"
      }
    }
  }
}
  1. Restart Claude Desktop and start using:

Create a Pix charge for R$25.50 to Maria Silva for lunch

Cursor (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-mcp or pix-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 βœ…

  • generateStaticPix tool

  • Static 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 banks

  • Static 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

  1. Fork the repository

  2. Create a feature branch

  3. Make your changes

  4. Add tests if applicable

  5. Submit a pull request

πŸ“ž Support


Made with ❀️ for the Brazilian Pix ecosystem

Available Tools

2 tools
generateStaticPixB

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

    A3.5/5.0

    Scored across 2 tools

    Disambiguation5/5

    The two tools have completely distinct purposes: one generates a static Pix QR code, the other checks server health. No ambiguity or overlap exists.

    Naming Consistency4/5

    Both tools use camelCase, but one starts with a verb (generateStaticPix) and the other with a noun (healthCheck). Minor inconsistency but still readable.

    Tool Count2/5

    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.

    Completeness2/5

    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

    Related MCP Servers