🤖 MCP Server

finan-mcp enables AI agents (Claude, GPT, Cursor, etc.) to interact with Finan's Open Banking, Payment, and Business APIs via the Model Context Protocol.

v2.0 — Complete rewrite using official @modelcontextprotocol/sdk. All 20 tools verified against production API.

Install

npm install -g finan-mcp

Or run directly with npx:

npx finan-mcp

Get API Credentials

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

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

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

Tools (20)

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", ...)

"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: "...")

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)

tip

Agents never need to compute signatures — the MCP server handles it automatically 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

Links

• npm Package
• Source Code
• Discord