Chuyển tới nội dung chính
Phiên bản: 1.4.0

Hướng dẫn kết nối

Hướng dẫn từng bước cài đặt và kết nối MCP Server với Claude Desktop để sử dụng các công cụ truy vấn hóa đơn đầu vào.

1. Cài đặt với Docker (Khuyến nghị)​

Bước 1 — Clone hoặc tạo thư mục dự án​

mkdir input-invoice-mcp && cd input-invoice-mcp

Bước 2 — Tạo file .env​

cp .env.example .env

Nội dung file .env:

INVOICE_API_URL=https://sanbox-api.tconnect.vn/invoice/api/v2/call

Bước 3 — Build và khởi động container​

docker-compose up --build

Kiểm tra container đang chạy:

docker-compose ps

2. Cài đặt không dùng Docker​

# Tạo virtual environment
python -m venv venv
source venv/bin/activate      # macOS / Linux
venv\Scripts\activate         # Windows

# Cài đặt dependencies
pip install -r requirements.txt

# Cấu hình môi trường
cp .env.example .env

# Chạy server
python server.py

3. Kết nối với Claude Desktop​

Bước 1 — Mở file cấu hình Claude Desktop​

Hệ điều hànhĐường dẫn
macOS~/Library/Application Support/Claude/claude_desktop_config.json
Windows%APPDATA%\Claude\claude_desktop_config.json

Bước 2 — Thêm cấu hình MCP Server​

Dùng Docker:

{
  "mcpServers": {
    "input-invoice": {
      "command": "docker",
      "args": [
        "compose",
        "-f", "/đường/dẫn/tới/input-invoice-mcp/docker-compose.yml",
        "run", "--rm", "input-invoice-mcp"
      ]
    }
  }
}

Dùng Python trực tiếp:

{
  "mcpServers": {
    "input-invoice": {
      "command": "python",
      "args": ["/đường/dẫn/tới/input-invoice-mcp/server.py"]
    }
  }
}

Bước 3 — Khởi động lại Claude Desktop​

Đóng hoàn toàn và mở lại Claude Desktop. Khi kết nối thành công, biểu tượng MCP sẽ xuất hiện trong giao diện chat.

4. Kiểm tra kết nối​

Sau khi kết nối thành công, thử gõ câu lệnh sau trong Claude Desktop:

Lấy 5 hóa đơn mới nhất loại GTGT

Claude sẽ tự động gọi tool list_invoices với domain filter phù hợp.

5. Ví dụ sử dụng​

Câu lệnhTool được gọiDomain filter
"Lấy hóa đơn của MST 0123456789"search_invoices_by_buyerbuyerTaxCode = "0123456789"
"Hóa đơn tháng 1/2026"search_invoices_by_date_rangedate_from=2026-01-01, date_to=2026-01-31
"Chi tiết hóa đơn số 6"get_invoice_detailinvoice_no=6
"Hóa đơn bán hàng chưa điều chỉnh"list_invoicesinvoiceType=2, invoiceStatus=1
important

Đảm bảo INVOICE_API_URL trong file .env trỏ đúng môi trường (dev hoặc production) trước khi kết nối với Claude Desktop.

ghi chú

MCP Server sử dụng stdio transport — server chỉ chạy khi Claude Desktop gọi đến và tự động tắt sau khi phiên kết thúc. Không cần giữ server chạy liên tục ở chế độ nền.