How do I use KiotViet MCP Server?

This server does not currently have a deployable release on Glama. Follow the repository's setup instructions to install and configure it for your MCP client, including any required credentials and local dependencies.

KiotViet MCP Server

by haudnn

Overview Schema Source Related Servers Discussions Admin

TypeScript

Hybrid

KiotViet MCP Server

MCP (Model Context Protocol) Server cho KiotViet Public API — Kết nối AI assistant với hệ thống quản lý bán hàng KiotViet.

Tính năng

36 tools bao phủ đầy đủ KiotViet Public API
Auto token refresh — Token 1 giờ được tự động làm mới trước khi hết hạn
Middleware chain — Error handler, validation, rate limit, pagination
2 transport mode — stdio (Claude Desktop) và HTTP (multi-session, Streamable HTTP + SSE legacy)
5 preset — Chọn nhóm tool phù hợp với nhu cầu
Docker ready — Build và deploy với Docker Compose

Related MCP server: Haravan MCP

Yêu cầu

Node.js >= 18
Tài khoản KiotViet với quyền truy cập Public API
Client ID, Client Secret, Retailer name từ Thiết lập cửa hàng → Thiết lập kết nối API

Cài đặt

# Clone và cài dependencies
git clone <repo-url>
cd kiotviet-mcp
npm install
npm run build

Cấu hình

Tạo file .env từ template:

cp .env.example .env

Điền thông tin:

KIOTVIET_CLIENT_ID=your_client_id
KIOTVIET_CLIENT_SECRET=your_client_secret
KIOTVIET_RETAILER=your_retailer_name

Sử dụng

Claude Desktop (stdio)

Thêm vào claude_desktop_config.json:

{
  "mcpServers": {
    "kiotviet": {
      "command": "node",
      "args": ["/path/to/kiotviet-mcp/dist/cli.js", "mcp"],
      "env": {
        "KIOTVIET_CLIENT_ID": "your_client_id",
        "KIOTVIET_CLIENT_SECRET": "your_client_secret",
        "KIOTVIET_RETAILER": "your_retailer_name"
      }
    }
  }
}

Chạy thủ công

# stdio mode
node dist/cli.js mcp --client-id X --client-secret Y --retailer Z

# HTTP mode
node dist/cli.js mcp --client-id X --client-secret Y --retailer Z --mode http --port 3000

Docker

# Build image
docker build -t kiotviet-mcp .

# Chạy container
docker run -d -p 3000:3000 \
  -e KIOTVIET_CLIENT_ID=your_client_id \
  -e KIOTVIET_CLIENT_SECRET=your_client_secret \
  -e KIOTVIET_RETAILER=your_retailer_name \
  kiotviet-mcp

Endpoints:

Health check: http://localhost:3000/health
Streamable HTTP (khuyến nghị): http://localhost:3000/mcp
SSE legacy: http://localhost:3000/sse

Tools

Xem danh sách tools

# Tất cả tools
node dist/cli.js tools

# Theo project
node dist/cli.js tools --project products

# Xem presets
node dist/cli.js tools --presets

Danh sách tools theo nhóm

Nhóm	Tools
categories	`kiotviet_categories_list`
products	`list`, `get_by_id`, `get_by_code`, `create`, `update`, `delete`
customers	`list`, `get_by_id`, `get_by_code`, `create`, `update`
customers	`kiotviet_customer_groups_list`
orders	`list`, `get`, `create`, `update`, `cancel`
invoices	`list`, `get_by_id`, `get_by_code`, `create`, `update`, `cancel`
purchase-orders	`list`, `get`, `create`
branches	`kiotviet_branches_list`
users	`kiotviet_users_list`
suppliers	`kiotviet_suppliers_list`
bank-accounts	`kiotviet_bank_accounts_list`
cashbook	`kiotviet_cashbook_list`
webhooks	`list`, `create`, `update`, `delete`

Presets

Preset	Mô tả	Số tools
`preset.default`	Tất cả tools	36
`preset.readonly`	Chỉ GET — an toàn cho môi trường read-only	21
`preset.products`	Hàng hóa + nhóm hàng	7
`preset.sales`	Đơn hàng + hóa đơn + khách hàng	17
`preset.inventory`	Hàng hóa + nhập kho + nhà cung cấp	11

Kích hoạt preset qua CLI:

node dist/cli.js mcp --tools "preset.readonly" ...

F&B Mode

Dùng cho nhà hàng, quán cà phê (API F&B):

KIOTVIET_BASE_URL=https://publicfnb.kiotapi.com

Xác thực

KiotViet dùng OAuth 2.0 Client Credentials. Token có hiệu lực 1 giờ và được tự động làm mới trước khi hết hạn (buffer 5 phút).

Token endpoint: https://id.kiotviet.vn/connect/token

Cấu trúc dự án

src/
├── auth/
│   └── token-manager.ts        # Client Credentials + auto-refresh
├── mcp-server/
│   ├── init.ts                 # Khởi tạo server, đăng ký tools
│   └── transport/
│       ├── stdio.ts            # stdio transport
│       └── sse.ts              # HTTP/SSE transport
├── mcp-tool/
│   ├── types.ts                # McpTool, MiddlewareContext...
│   ├── handler.ts              # KiotViet API handler
│   ├── registry.ts             # Đăng ký tất cả tools + presets
│   ├── presets.ts              # Resolver preset/filter
│   ├── middleware/
│   │   ├── chain.ts
│   │   ├── error-handler.ts
│   │   ├── rate-limiter.ts
│   │   ├── pagination.ts
│   │   └── validation.ts
│   └── tools/                  # 13 modules tool definitions
└── utils/
    ├── config.ts
    ├── http-client.ts
    └── logger.ts
Dockerfile
docker/
└── docker-compose.yml

Scripts

npm run build        # Build TypeScript → dist/
npm run dev          # Chạy trực tiếp với ts-node
npm run format       # Format code với Prettier
npm test             # Chạy tests
npm run test:coverage

Giới hạn API

Thông số	Giá trị
pageSize tối đa	100 bản ghi/request
Token TTL	3600 giây (1 giờ)
Webhook timeout	5 giây
Base URL Retail	`https://public.kiotapi.com`
Base URL F&B	`https://publicfnb.kiotapi.com`

License

MIT

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

This server cannot be deployed

One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

Maintenance

ActivityInactive

ResponsivenessNo recent community issues

Resources

Related MCP Connectors

feeefapp-mcp
ai.smithery
Enable AI assistants to interact seamlessly with Feeef e-commerce stores, products, and orders usi…
E-commerce & Retail App Automation
2
https://server.smithery.ai/@feeefapp/mcp/mcp
Store MCP
com.store-mcp
Connect AI to store orders, products and inventory with scoped access and human approvals.
E-commerce & Retail ERP Systems
1
https://store-mcp.com/mcp
mcpA
my.taokeh
Malaysian SME accounting, e-Invoice and payroll for your AI. 77 tools; writes are approved drafts.
ERP Systems Finance
771
https://taokeh.my/mcp
Composio
io.github.ComposioHQ
Connect AI agents to 1000+ apps with managed authentication and tool-calling.
Agent Orchestration App Automation
21
https://connect.composio.dev/mcp

Related MCP Servers

Finizi B4B MCP Server
finizi-app
A
license
Not graded
quality
Not graded
maintenance
Enables AI assistants to interact with the Finizi B4B platform through 15 comprehensive tools for managing business entities, invoices, vendors, and products. Features secure JWT authentication, automatic retries, and full business-to-business workflow integration through natural language commands.
Updated a year ago (2025-10-02 07:44 UTC)
MIT
Haravan MCP
E-commerce & Retail Finance
pluginmd
A
license
Not graded
quality
D
maintenance
Enables AI assistants to interact with Haravan e-commerce platforms via MCP protocol for natural language management of stores. Provides 7 smart analytics tools for insights and 63 base tools for CRUD operations on products, orders, customers, and inventory.
Updated 7 months ago (2026-04-06 04:21 UTC)
21
Apache 2.0
pancake-pos-mcp
E-commerce & Retail CRM
nguyennguyenit
A
license
Not graded
quality
C
maintenance
Enables AI assistants to manage Vietnamese e-commerce POS operations including orders, products, customers, inventory, supply chain, sales, CRM, and multi-channel integration via Pancake POS API.
Updated a month ago (2026-10-08 09:43 UTC)
32
MIT
Toast MCP Server
ERP Systems Payments & Billing E-commerce & Retail
BusyBee3333
A
license
A
quality
C
maintenance
Enables AI assistants to manage restaurant operations by integrating with Toast POS, including orders, menus, employees, payments, inventory, and reporting through 50+ tools and 18 React apps.
Updated 3 months ago (2026-08-28 12:05 UTC)
8
16
MIT

KiotViet MCP Server

Tính năng

Yêu cầu

Cài đặt

Cấu hình

Sử dụng

Claude Desktop (stdio)

Chạy thủ công

Docker

Tools

Xem danh sách tools

Danh sách tools theo nhóm

Presets

F&B Mode

Xác thực

Cấu trúc dự án

Scripts

Giới hạn API

License

Tool Schema Changelog

Maintenance

Resources

Related MCP Connectors

Related MCP Servers

Finizi B4B MCP Server

Haravan MCP

pancake-pos-mcp

Toast MCP Server