Pix MCP Server v2.1.0

1# Pix MCP Server v2.1.0
2 
3A lightweight Model Context Protocol (MCP) server that enables AI agents (Claude, Cursor, Windsurf) to generate static Pix QR codes via natural-language prompts.
4 
5## 🚀 Features
6 
7- **🔧 MCP Tool**:
8  - `generateStaticPix` - Generate static Pix QR codes for any Pix key (no API required)
9- **🚀 Production-ready**: Comprehensive error handling and logging
10- **🔒 Type-safe**: Full TypeScript implementation with Zod validation
11- **📱 QR Code generation**: Automatic QR code creation for Pix payments
12- **📦 Zero Dependencies**: No external API keys or services required
13- **🌍 Open & Accessible**: Works without any registration or credentials
14- **✅ EMV 4.0 Compliant**: Follows BACEN PIX standards with proper CRC16-CCITT validation
15 
16## 🚀 Quick Start
17 
18```bash
19# Install globally
20npm install -g pix-mcp
21 
22# Run in MCP mode (for Claude Desktop)
23pix-mcp
24 
25# Run in HTTP mode (for web services)
26MCP_MODE=http pix-mcp
27```
28 
29## 🔧 Usage
30 
31### MCP Mode (Default)
32 
33```bash
34# Start in MCP mode for Claude Desktop integration
35pix-mcp
36```
37 
38### HTTP Mode
39 
40```bash
41# Start in HTTP mode on port 3000
42MCP_MODE=http pix-mcp
43```
44 
45### Making Requests
46 
47#### HTTP API
48 
49```bash
50curl -X POST http://localhost:3000/tools/call \
51  -H "Content-Type: application/json" \
52  -d '{
53    "name": "generateStaticPix",
54    "arguments": {
55      "pixKey": "10891990909",
56      "amount": 100.50,
57      "recipientName": "Franco Camelo Aguzzi",
58      "recipientCity": "Florianopolis"
59    }
60  }'
61```
62 
63#### MCP Tool
64 
65```typescript
66const result = await mcpClient.callTool('generateStaticPix', {
67  pixKey: '10891990909',
68  amount: 100.5,
69  recipientName: 'Franco Camelo Aguzzi',
70  recipientCity: 'Florianopolis',
71});
72```
73 
74## 🚀 Deployment
75 
76### Railway
77 
78[![Deploy on Railway](https://railway.app/button.svg)](https://railway.app/new/template?template=https%3A%2F%2Fgithub.com%2FRegenerating-World%2Fpix-mcp)
79 
80**⚠️ Important:** After deploying to Railway, add these environment variables in the Railway dashboard:
81 
82- `MCP_MODE=http`
83- `NODE_ENV=production` (optional)
84 
85### Manual Deployment
86 
87```bash
88# Clone the repository
89git clone https://github.com/Regenerating-World/pix-mcp.git
90cd pix-mcp
91 
92# Install dependencies
93npm install
94 
95# Build the project
96npm run build
97 
98# Start the server in HTTP mode
99MCP_MODE=http NODE_ENV=production node dist/index.js
100```
101 
102## 📝 License
103 
104MIT
105 
106## 🔧 Configuration
107 
108### Environment Variables
109 
110- `MCP_MODE`: Server mode (`stdio` for MCP, `http` for HTTP API) - Default: `stdio`
111- `NODE_ENV`: Environment (`development`/`production`) - Default: `development`
112- `PORT`: HTTP port when in HTTP mode - Default: `3000`
113 
114## 🤖 Usage with AI Tools
115 
116### Claude Desktop
117 
1181. Install the package globally:
119 
120```bash
121npm install -g pix-mcp
122```
123 
1242. 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):
125 
126```json
127{
128  "mcpServers": {
129    "pix-mcp": {
130      "command": "npx",
131      "args": ["pix-mcp"],
132      "env": {
133        "MCP_MODE": "stdio"
134      }
135    }
136  }
137}
138```
139 
1403. Restart Claude Desktop and start using:
141 
142```
143Create a Pix charge for R$25.50 to Maria Silva for lunch
144```
145 
146### Cursor (with MCP support)
147 
148Add to your Cursor MCP settings:
149 
150```json
151{
152  "mcpServers": {
153    "pix-mcp": {
154      "command": "pix-mcp"
155    }
156  }
157}
158```
159 
160### Windsurf (with MCP support)
161 
162Configure in Windsurf MCP settings:
163 
164```json
165{
166  "pix-mcp": {
167    "command": "npx pix-mcp",
168    "args": []
169  }
170}
171```
172 
173### Any MCP-compatible tool
174 
175Your tool should support MCP servers. Configure using:
176 
177- **Command**: `npx pix-mcp` or `pix-mcp` (if installed globally)
178- **Protocol**: stdio
179- **Environment**: `MCP_MODE=stdio`
180 
181## 🔨 Available Tools
182 
183### `generateStaticPix`
184 
185Creates a static Pix payment QR code following BACEN EMV 4.0 standards.
186 
187**Parameters:**
188 
189- `pixKey` (string): Valid Pix key (email, phone, CPF, CNPJ, or random key)
190- `amount` (number): Payment amount in BRL (0.01 to 999,999.99)
191- `recipientName` (string): Name of the payment recipient (max 25 chars)
192- `recipientCity` (string): City of the payment recipient (max 15 chars)
193 
194**Returns:**
195 
196- Payment details (amount, recipient, city)
197- Pix copy-paste code (EMV format)
198- QR code image (base64 data URL)
199- Success status and message
200 
201**Supported Pix Key Types:**
202 
203- 📧 Email: `example@email.com`
204- 📱 Phone: `+5511999999999`
205- 👤 CPF: `12345678901` (11 digits)
206- 🏢 CNPJ: `12345678000195` (14 digits)
207- 🔑 Random Key: `123e4567-e89b-12d3-a456-426614174000` (UUID format)
208 
209## 🏗️ Development
210 
211```bash
212# Development mode with hot reload
213npm run dev
214 
215# Run tests
216npm test
217 
218# Build for production
219npm run build
220 
221# Lint code
222npm run lint
223 
224# Format code
225npm run format
226```
227 
228## 🗺️ Roadmap
229 
230### Phase 1: MVP ✅
231 
232- [x] `generateStaticPix` tool
233- [x] Static Pix QR code generation
234- [x] QR code generation
235- [x] Claude Desktop compatibility
236- [x] EMV 4.0 compliance
237- [x] CRC16-CCITT validation
238- [x] All Pix key types support
239- [x] Public deployment
240- [x] MCP server configuration files
241- [x] Multi-tool compatibility
242 
243### Phase 2: MCP Discovery
244 
245- [ ] Register with MCP registry
246- [ ] Add to community MCP directories
247- [ ] Integration examples for more tools
248 
249## 🔒 Security & Validation
250 
251- ✅ EMV 4.0 standard compliance
252- ✅ CRC16-CCITT checksum validation
253- ✅ Input validation with Zod schemas
254- ✅ Pix key format validation
255- ✅ Comprehensive error handling
256- ✅ Type-safe TypeScript implementation
257 
258## ⚠️ Important Notes
259 
260- **CPF/CNPJ Keys**: Must be valid and registered as Pix keys
261- **Test Data**: Avoid using fake CPFs like `12345678900` - they will be rejected by banks
262- **Static Codes**: No expiration, recipient must check payments manually
263- **Validation**: All codes are EMV-compliant and pass bank validation
264 
265## 📝 License
266 
267MIT License - see [LICENSE](LICENSE) file for details.
268 
269## 🤝 Contributing
270 
2711. Fork the repository
2722. Create a feature branch
2733. Make your changes
2744. Add tests if applicable
2755. Submit a pull request
276 
277## 📞 Support
278 
279- GitHub Issues: [Report bugs or request features](https://github.com/Regenerating-World/pix-mcp/issues)
280- Documentation: Available in this README
281 
282---
283 
284Made with ❤️ for the Brazilian Pix ecosystem
285