Pekao MCP Server

A Model Context Protocol (MCP) server for the Pekao Polish API (PolishAPI 2.1.1). This server exposes banking operations as MCP tools that can be used by AI assistants like Claude.

Features

• Account Information Service (AIS): List accounts, view balances, transaction history

• Payment Initiation Service (PIS): Create domestic, SEPA, and international transfers

• Confirmation of Funds (CAF): Check if funds are available

• OAuth2 Authorization: Secure authentication flow

Related MCP server: starling-bank-mcp

Prerequisites

• Node.js 18+

• Pekao API credentials (client ID, client secret)

• QSEAL certificate and private key for request signing

Getting API Credentials

Pekao uses the PolishAPI standard with automatic TPP (Third Party Provider) registration. You need PSD2-compliant certificates to register and use the API.

1. Obtain PSD2 Certificates

You need two separate certificates (using the same certificate for both purposes is not allowed):

Where to obtain certificates:

For production, get certificates from a qualified Trust Service Provider (TSP):

• Krajowa Izba Rozliczeniowa (KIR)

• Asseco Data Systems

• Certum (Asseco)

• Other eIDAS-qualified providers listed on the EU Trusted List

The certificates must contain PSD2 roles in the QC_Statement:

• PSP_AI - Account Information Service Provider (AISP) - for AIS

• PSP_PI - Payment Initiation Service Provider (PISP) - for PIS

• PSP_IC - Payment Instrument Issuing Service Provider (PIISP) - for CAF

• PSP_AS - Account Servicing Payment Service Provider (ASPSP)

For sandbox/testing, contact Pekao for test certificates or use certificates from a test TSP.

2. Register Your Application

Registration is done automatically via the /auth/v2_1_1.1/register API endpoint. This MCP server includes a registration tool, but you can also register manually.

Required for registration:

• QWAC certificate for mTLS connection

• QSealC certificate for signing the request

• A software_statement JWT containing your application details

Software Statement Structure:

{
  "redirect_uris": ["https://your-app.com/callback"],
  "iss": "PSDES-ABC-ABC123",
  "client_name": "Your App Name",
  "sub_contact_email": "contact@your-company.com",
  "logo_uri": "https://your-app.com/logo.png",
  "jwks_uri": "https://your-app.com/jwks.json",
  "client_desc": "Application description",
  "sub": "PL-PFSA-YOUR-LICENSE-NUMBER",
  "sub_name": "Your Company Sp. z o.o.",
  "scope": "ais ais-accounts pis"
}

The software_statement must be signed as a JWT using your QSealC certificate.

3. Receive Your Credentials

After successful registration, you'll receive:

Important: Store these credentials securely. They are only returned once during registration.

4. Prepare Certificate Files

Save your certificates in PEM format in the certs/ directory:

QSealC Certificate (certificate.pem):

-----BEGIN CERTIFICATE-----
MIIxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx...
-----END CERTIFICATE-----

Private Key (private-key.pem):

-----BEGIN PRIVATE KEY-----
MIIxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx...
-----END PRIVATE KEY-----

5. Configure the Key ID

The PEKAO_KEY_ID is the kid (Key ID) parameter from your QSealC certificate. You can find it:

• In your certificate's metadata

• By checking the certificate with OpenSSL: openssl x509 -in certificate.pem -text

• From your TSP's certificate issuance documentation

Environment Variables Reference

API Endpoints

Installation

git clone https://github.com/xnetcat/pekao-mcp.git
cd pekao-mcp
npm install
npm run build

Configuration

1. Copy the example environment file:

cp .env.example .env

2. Edit .env with your credentials:

PEKAO_CLIENT_ID=your-client-id
PEKAO_CLIENT_SECRET=your-client-secret
PEKAO_ENVIRONMENT=sandbox
PEKAO_CERT_PATH=./certs/certificate.pem
PEKAO_KEY_PATH=./certs/private-key.pem
PEKAO_KEY_ID=your-key-id
PEKAO_REDIRECT_URI=http://localhost:3000/callback

3. Place your QSEAL certificate and private key in the certs/ directory.

Usage

Claude Desktop

Add to your Claude Desktop configuration file:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "pekao": {
      "command": "node",
      "args": ["/path/to/pekao-mcp/dist/index.js"],
      "env": {
        "PEKAO_CLIENT_ID": "your-client-id",
        "PEKAO_CLIENT_SECRET": "your-client-secret",
        "PEKAO_ENVIRONMENT": "sandbox",
        "PEKAO_CERT_PATH": "/path/to/pekao-mcp/certs/certificate.pem",
        "PEKAO_KEY_PATH": "/path/to/pekao-mcp/certs/private-key.pem",
        "PEKAO_KEY_ID": "your-key-id",
        "PEKAO_REDIRECT_URI": "http://localhost:3000/callback"
      }
    }
  }
}

Claude Code (CLI)

Add to your Claude Code MCP settings:

claude mcp add pekao node /path/to/pekao-mcp/dist/index.js

Or add to your project's .mcp.json:

{
  "mcpServers": {
    "pekao": {
      "command": "node",
      "args": ["/path/to/pekao-mcp/dist/index.js"],
      "env": {
        "PEKAO_CLIENT_ID": "your-client-id",
        "PEKAO_CLIENT_SECRET": "your-client-secret",
        "PEKAO_ENVIRONMENT": "sandbox",
        "PEKAO_CERT_PATH": "/path/to/pekao-mcp/certs/certificate.pem",
        "PEKAO_KEY_PATH": "/path/to/pekao-mcp/certs/private-key.pem",
        "PEKAO_KEY_ID": "your-key-id",
        "PEKAO_REDIRECT_URI": "http://localhost:3000/callback"
      }
    }
  }
}

Cursor

Add to Cursor's MCP configuration in Settings > MCP Servers:

{
  "pekao": {
    "command": "node",
    "args": ["/path/to/pekao-mcp/dist/index.js"],
    "env": {
      "PEKAO_CLIENT_ID": "your-client-id",
      "PEKAO_CLIENT_SECRET": "your-client-secret",
      "PEKAO_ENVIRONMENT": "sandbox",
      "PEKAO_CERT_PATH": "/path/to/pekao-mcp/certs/certificate.pem",
      "PEKAO_KEY_PATH": "/path/to/pekao-mcp/certs/private-key.pem",
      "PEKAO_KEY_ID": "your-key-id",
      "PEKAO_REDIRECT_URI": "http://localhost:3000/callback"
    }
  }
}

Using npx (after publishing to npm)

{
  "mcpServers": {
    "pekao": {
      "command": "npx",
      "args": ["pekao-mcp"],
      "env": {
        "PEKAO_CLIENT_ID": "your-client-id",
        "PEKAO_CLIENT_SECRET": "your-client-secret"
      }
    }
  }
}

Available Tools

Authorization

Account Information

Payment Initiation

Confirmation of Funds

Example Usage

Once configured, you can ask Claude to:

• "Show me my Pekao bank accounts"

• "What's my account balance?"

• "List my recent transactions"

• "Transfer 100 PLN to account 12345678901234567890123456"

• "Check if I have 500 PLN available"

Development

# Install dependencies
npm install

# Build
npm run build

# Run in development mode
npm run dev

# Test with MCP Inspector
npx @modelcontextprotocol/inspector node dist/index.js

Technical Details

JWS Signature Format

All API requests require a detached JWS signature in the X-JWS-SIGNATURE header. The signature format is:

[base64url-encoded-header]..[base64url-encoded-signature]

The payload section is empty (detached) to avoid duplicating request data. This MCP server handles JWS signing automatically.

JWS Header Structure:

{
  "alg": "RS256",
  "typ": "JWT",
  "kid": "your-key-id",
  "x5c": ["base64-encoded-certificate"]
}

Required HTTP Headers

All requests include:

• X-IBM-Client-Id - Your client ID

• X-IBM-Client-Secret - Your client secret

• X-JWS-SIGNATURE - Detached JWS signature

• X-REQUEST-ID - UUID v4 for request tracking

• Authorization: Bearer <token> - For authenticated endpoints

• Content-Type: application/json

• Accept: application/json

• Accept-Encoding: gzip

• Accept-Language: pl

• Accept-Charset: utf-8

Rate Limits

For AIS queries without user presence (automatic queries by TPP):

• Maximum 4 requests per 24 hours per consent

• Transaction history limited to 90 days by default

• Exceeding limits returns 429 Too Many Requests

Strong Customer Authentication (SCA)

SCA is performed on Pekao's side using:

• SMS codes

• PeoPay mobile authorization

For multiple-use AIS consents, SCA is required every 90 days.

API Documentation

This server implements the Pekao Polish API (PolishAPI 2.1.1). For full API documentation, see:

• Pekao API Portal

• PolishAPI Standard

• PolishAPI Swagger Specification

Limitations

Based on Pekao's implementation of PolishAPI:

• No bundle transfers for retail customers (only corporate via PekaoBiznes24)

• No SORBNET2, Blue Cash, or TARGET payment systems for retail

• No getMultiplePayments - only for corporate customers

• No getTransactionsPending for retail customers (Pekao24)

• No decoupled SCA - only redirect-based authentication

• No account list consent flow - accounts must be specified by TPP

• CAF service - currently returns unavailable for all accounts

License

MIT