finan-mcp

MCP server for Finan Open API — enables AI agents (Claude, GPT, Cursor, etc.) to interact with Finan's Open Banking, Payment, and Business APIs.

v2.1 — Added QR code generation tool. Complete rewrite using official @modelcontextprotocol/sdk. Replaces v1.x (fastmcp-based). All 21 tools verified against production API.

Install

npm install -g finan-mcp

Or run directly with npx:

npx finan-mcp

Configuration

Claude Code

Add to ~/.claude/settings.json:

{
  "mcpServers": {
    "finan": {
      "command": "npx",
      "args": ["-y", "finan-mcp"],
      "env": {
        "FINAN_CLIENT_ID": "your-client-id",
        "FINAN_SECRET_KEY": "your-secret-key"
      }
    }
  }
}

Claude Desktop

Add to claude_desktop_config.json:

{
  "mcpServers": {
    "finan": {
      "command": "npx",
      "args": ["-y", "finan-mcp"],
      "env": {
        "FINAN_CLIENT_ID": "your-client-id",
        "FINAN_SECRET_KEY": "your-secret-key"
      }
    }
  }
}

Cursor / Windsurf

Add to .cursor/mcp.json or .windsurf/mcp.json:

{
  "mcpServers": {
    "finan": {
      "command": "npx",
      "args": ["-y", "finan-mcp"],
      "env": {
        "FINAN_CLIENT_ID": "your-client-id",
        "FINAN_SECRET_KEY": "your-secret-key"
      }
    }
  }
}

n8n

Use the MCP Client node with command transport:

| Field | Value | |-------|-------| | Command | npx | | Arguments | -y finan-mcp | | Environment | FINAN_CLIENT_ID=xxx, FINAN_SECRET_KEY=xxx |

Get API Credentials

1. Sign up at book.finan.one
2. Go to Settings > Open API
3. Copy your Client ID and Secret Key

Tools (21)

QR Code

| Tool | Description | |------|-------------| | generate_qr_code | Generate a QR code image for payment transactions. Returns base64-encoded PNG |

Parameters:

| Name | Type | Required | Description | |------|------|----------|-------------| | data | string | Yes | Code content to encode (e.g. payment string, URL) | | border | int | Yes | Border frame width around the QR code (0 for no border) |

Account

| Tool | Description | |------|-------------| | get_master_bank_accounts | List master bank accounts. Filter by id or account_number | | get_bank_accounts | List bank accounts. Filter by id or account_number | | get_bank_account | Get a specific bank account by ID | | create_bank_account | Create a new bank account under a master account |

Payment

| Tool | Description | |------|-------------| | create_payment | Create a payment request. Returns QR code (bank_transfer) or payment URL (card/momo) | | get_payments | List payments. Filter by reference_type and reference_id | | get_payment | Get a specific payment by ID |

Customer

| Tool | Description | |------|-------------| | create_customer | Create a new customer (personal or company) | | get_customers | List all customers (paginated) | | get_customer | Get a specific customer by ID | | update_customer | Update a customer (full replace — all required fields must be included) | | delete_customer | Delete a customer |

Product

| Tool | Description | |------|-------------| | create_product | Create a product with sale/purchase pricing | | get_products | List all products (paginated) | | get_product | Get a specific product by ID | | delete_product | Delete a product |

Invoice

| Tool | Description | |------|-------------| | create_invoice | Create an invoice linked to customer + products | | get_invoices | List all invoices (paginated) | | get_invoice | Get a specific invoice by ID | | delete_invoice | Delete an invoice |

Usage Examples

Once configured, ask your AI agent naturally:

"Show me all bank accounts"
> calls get_bank_accounts()

"Create a 500,000 VND payment via bank transfer"
> calls create_payment(amount: 500000, payment_method: "bank_transfer", ...)

"Generate a QR code for this payment link"
> calls generate_qr_code(data: "https://pay.finan.vn/xxx", border: 0)

"Create an invoice for customer CUST-001 with product SKU-001, due in 7 days"
> calls create_invoice(customer_code: "CUST-001", items: [{code: "SKU-001", ...}], ...)

"Delete customer MCP-TEST-001"
> calls delete_customer(customer_id: "...")

Environment Variables

| Variable | Required | Default | Description | |----------|----------|---------|-------------| | FINAN_CLIENT_ID | Yes | — | Your Finan client ID | | FINAN_SECRET_KEY | Yes | — | Your Finan secret key | | FINAN_BASE_URL | No | https://api.finan.one/open | Override API base URL |

How It Works

The MCP server handles Finan's SHA-256 signature authentication automatically:

signature = SHA256(secret_key + "_" + METHOD + "_" + path + "_" + payload + "_" + timestamp)

Every request includes:

• x-client-id — your client ID
• x-signature — computed SHA-256 signature
• x-timestamp — current Unix timestamp (valid 30 seconds)

Agents never need to compute signatures — the server does it for every tool call.

API Response Format

All tools return the raw API response:

{
  "message": { "content": "Thực thi API thành công" },
  "code": 102000,
  "request_id": "abc123...",
  "data": { ... },
  "meta": { "page": 1, "page_size": 50, "total_pages": 1, "total_rows": 5 }
}

Development

git clone https://code.finan.one/ai-agent/book-mcp.git
cd book-mcp
npm install

# Development with hot reload
FINAN_CLIENT_ID=xxx FINAN_SECRET_KEY=xxx npm run dev

# Build for production
npm run build

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

Changelog

v2.1.0 (2026-04-01)

• Added generate_qr_code tool — generates QR code images for payment transactions
• Returns base64-encoded PNG via MCP image content type

v2.0.0 (2026-03-31)

• Complete rewrite using official @modelcontextprotocol/sdk
• 20 tools covering all Finan Open API endpoints
• All tools verified against production API
• Correct response wrapper parsing (message, code, request_id, data, meta)
• SHA-256 signature generation with query string support
• Proper error handling with descriptive messages

v1.x

• Initial release using fastmcp
• Basic tool support

Links

• Finan Open API Docs
• Source Code
• npm Package
• Discord

License

MIT