Skip to main content
Glama
Regenerating-World

pix-mcp

by Regenerating-World
OverviewSchemaSourceRelated ServersDiscussionsAdmin
TypeScript
Remote

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: QrVerloz 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)

ParametersJSON Schema
NameRequiredDescriptionDefault
pixKeyYesPix key (email, phone +5511999999999, CPF, CNPJ, or random key)
amountYesPayment amount in BRL (Brazilian Reais)
recipientNameYesName of the payment recipient (max 25 chars)
recipientCityYesCity of the payment recipient

TDQS

B3.4/5.0
Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

The description notes that the tool 'works without API credentials', which is a behavioral trait. However, it does not disclose what the tool returns (no output schema) or any side effects. Annotations are absent, so the description carries the burden, but it partially fails to describe the output or other behaviors.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single sentence that conveys the core purpose and a key benefit. It is front-loaded with the verb and resource, making it easy to scan. Every word adds value; there is no redundancy.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness2/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the lack of an output schema, the description should ideally mention what the tool returns (e.g., a QR code image or data). It does not. Additionally, with 4 required parameters, there is no guidance on their interrelations or constraints beyond the schema. The description is too brief for a tool that generates a QR code.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so the baseline is 3. The description adds no additional meaning beyond the schema's parameter descriptions. The tool name and description imply the parameters are needed, but no further semantic clarification is provided.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the verb 'Generate' and the resource 'static Pix QR code', with the qualification 'for any Pix key'. It also mentions a key benefit ('works without API credentials'), which further clarifies its purpose. The sibling 'healthCheck' is distinctly different, so no confusion.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

There is no explicit guidance on when to use this tool versus alternatives. The only sibling is 'healthCheck', which is clearly unrelated, but the description does not provide any context about when generating a static Pix QR code is preferable or any prerequisites. The benefit of no API credentials is mentioned but not framed as a usage guideline.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

healthCheckA

Check the health status of the Pix MCP server and providers

ParametersJSON Schema
NameRequiredDescriptionDefault

No parameters

TDQS

A3.9/5.0
Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations provided, so description must cover behavioral traits. It states 'Check the health status' implying a read-only operation, but does not disclose details like side effects, network calls, or response format, which is minimal but acceptable for a simple tool.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Single sentence, no wasted words, front-loaded with verb and resource. Perfectly concise.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

No output schema exists, so description should explain return value. It only says 'Check the health status' without detailing what the response contains (e.g., JSON, text, status codes). Adequate for a simple health check but lacking completeness.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

No parameters in input schema; schema coverage is 100% trivial. Baseline for 0 parameters is 4. Description adds no extra meaning, but it's not needed.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

Description clearly states verb 'Check' and resource 'health status of the Pix MCP server and providers'. It effectively differentiates from sibling tool 'generateStaticPix' which is for content generation, not health checking.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description implies usage for health checks but does not provide explicit when, when-not, or alternative guidance. For a simple health check, it's adequate but lacks context like 'use before making other calls'.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

  1. 2 tool updatesv2.1.1
    • First observedgenerateStaticPix
    • First observedhealthCheck
Deploy Server
One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

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.

Maintenance

ActivityInactive
ResponsivenessNo issues

Resources

Related MCP Connectors

Related MCP Servers

  • QR for Agent

    benswel
    A
    license
    A
    quality
    D
    maintenance
    Dynamic 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…).
    37
    3
    MIT

  • QrVerloz MCP Server

    neaj-Corp
    A
    license
    Not graded
    quality
    D
    maintenance
    QrVerloz lets AI agents create QR codes instantly — no account needed, active for 90 days, and claimable at any time to make them permanent. Retarget the destination URL whenever you need, without reprinting.
    3
    MIT

  • freeqrcode-mcp-server

    flarewand
    A
    license
    B
    quality
    F
    maintenance
    Enables AI assistants to generate QR codes for URLs, text, vCard, WiFi, email, and phone numbers with customizable size, colors, and error correction.
    1
    4 npm
    1
    MIT