🤖 MCP Server

finan-mcp cho phép các AI agent (Claude, GPT, Cursor, v.v.) tương tác với API Ngân hàng mở, Thanh toán và Quản lý kinh doanh của Finan thông qua Model Context Protocol.

v2.0 — Viết lại hoàn toàn sử dụng @modelcontextprotocol/sdk chính thức. Tất cả 20 công cụ đã được xác minh trên API production.

Cài đặt

npm install -g finan-mcp

Hoặc chạy trực tiếp với npx:

npx finan-mcp

Lấy thông tin xác thực API

1. Đăng ký tại book.finan.one
2. Vào Cài đặt > Open API
3. Sao chép Client ID và Secret Key

Cấu hình

Claude Code

Thêm vào ~/.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

Thêm vào 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

Thêm vào .cursor/mcp.json hoặc .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

Sử dụng node MCP Client với command transport:

Trường	Giá trị
Command	npx
Arguments	-y finan-mcp
Environment	FINAN_CLIENT_ID=xxx, FINAN_SECRET_KEY=xxx

Biến môi trường

Biến	Bắt buộc	Mặc định	Mô tả
FINAN_CLIENT_ID	Có	—	Client ID của bạn
FINAN_SECRET_KEY	Có	—	Secret key của bạn
FINAN_BASE_URL	Không	https://api.finan.one/open	Ghi đè URL API

Danh sách công cụ (20)

Tài khoản

Công cụ	Mô tả
get_master_bank_accounts	Danh sách tài khoản ngân hàng chính. Lọc theo id hoặc account_number
get_bank_accounts	Danh sách tài khoản ngân hàng. Lọc theo id hoặc account_number
get_bank_account	Xem chi tiết một tài khoản ngân hàng theo ID
create_bank_account	Tạo tài khoản ngân hàng mới dưới tài khoản chính

Thanh toán

Công cụ	Mô tả
create_payment	Tạo yêu cầu thanh toán. Trả về mã QR (bank_transfer) hoặc URL thanh toán (card/momo)
get_payments	Danh sách thanh toán. Lọc theo reference_type và reference_id
get_payment	Xem chi tiết một thanh toán theo ID

Khách hàng

Công cụ	Mô tả
create_customer	Tạo khách hàng mới (cá nhân hoặc doanh nghiệp)
get_customers	Danh sách tất cả khách hàng (phân trang)
get_customer	Xem chi tiết một khách hàng theo ID
update_customer	Cập nhật khách hàng (thay thế toàn bộ — phải bao gồm tất cả trường bắt buộc)
delete_customer	Xóa khách hàng

Sản phẩm

Công cụ	Mô tả
create_product	Tạo sản phẩm với giá bán/giá mua
get_products	Danh sách tất cả sản phẩm (phân trang)
get_product	Xem chi tiết một sản phẩm theo ID
delete_product	Xóa sản phẩm

Hóa đơn

Công cụ	Mô tả
create_invoice	Tạo hóa đơn liên kết với khách hàng + sản phẩm
get_invoices	Danh sách tất cả hóa đơn (phân trang)
get_invoice	Xem chi tiết một hóa đơn theo ID
delete_invoice	Xóa hóa đơn

Ví dụ sử dụng

Sau khi cấu hình, bạn có thể hỏi AI agent bằng ngôn ngữ tự nhiên:

"Hiển thị tất cả tài khoản ngân hàng"
→ gọi get_bank_accounts()

"Tạo thanh toán 500.000 VND qua chuyển khoản"
→ gọi create_payment(amount: 500000, payment_method: "bank_transfer", ...)

"Tạo hóa đơn cho khách hàng CUST-001 với sản phẩm SKU-001, hạn thanh toán 7 ngày"
→ gọi create_invoice(customer_code: "CUST-001", items: [{code: "SKU-001", ...}], ...)

"Xóa khách hàng MCP-TEST-001"
→ gọi delete_customer(customer_id: "...")

Cách hoạt động

MCP server tự động xử lý xác thực chữ ký SHA-256 của Finan:

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

Mỗi request bao gồm:

• x-client-id — client ID của bạn
• x-signature — chữ ký SHA-256 được tính toán tự động
• x-timestamp — Unix timestamp hiện tại (hợp lệ trong 30 giây)

mẹo

Agent không cần tự tính chữ ký — MCP server xử lý tự động cho mọi lệnh gọi.

Định dạng phản hồi API

Tất cả công cụ trả về phản hồi API gốc:

{
  "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 }
}

Phát triển

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

# Phát triển với hot reload
FINAN_CLIENT_ID=xxx FINAN_SECRET_KEY=xxx npm run dev

# Build cho production
npm run build

# Test với MCP Inspector
npx @modelcontextprotocol/inspector node dist/index.js

Liên kết

• npm Package
• Mã nguồn
• Discord