Kiotviet MCP

MCP运维云端

提供方 dehuy69

运维云端 stdio · 本地进程 Token 社区 / 第三方
查看接入方式

一个无状态的MCP服务器,作为AI代理与KiotViet公共API之间的安全交互层,提供数据查询和操作工具。

一句话选型结论

按资料字段整理

Kiotviet MCP 属于运维云端类 MCP 服务器,stdio · 本地进程,Token,有可直接执行的安装命令。接入前先确认权限范围;涉及写入、删除或付款的操作,建议先在测试环境验证。

分类运维云端 传输方式stdio · 本地进程 鉴权Token 部署方式本地部署
GitHub 星标 2 仓库热度,无公开仓库时显示未标注
工具数 12 暴露给模型的工具数量
资源 / 提示词 0 / 0 资源与提示词模板数量
维护方 社区 / 第三方 核验等级 仅资料核对

工具与能力

运维云端
数量来自来源目录的标注,具体工具清单以官方文档为准
工具数量12暴露给模型可调用的工具个数
资源数量0可读取的资源条目
提示词数量0内置提示词模板数量

能力标签

适用场景

API代理Python本地部署无状态服务零售管理AI集成数据操作

安装与配置

stdio · 本地进程 Token
客户端在本机拉起子进程,数据不出本机
pip install -r requirements.txt

这条命令只是入口,具体启动参数请按官方文档补齐,不要直接照搬到别的服务器。

  1. 1
    准备运行环境

    stdio 服务在本地起进程,需要先装好 Node.js 等运行时,再按安装命令拉取依赖。

  2. 2
    安装服务

    复制上面的安装命令执行;命令里带占位符的位置,换成自己的密钥或路径。

  3. 3
    写入客户端配置

    在客户端的 MCP 配置里填好启动命令和参数,保存后完全退出客户端再打开,让新配置生效。

  4. 4
    验证是否可用

    连接成功后客户端会列出约 12 个工具,随便调一个只读工具确认能返回结果。

典型使用场景

3 类
按分类与标签整理的常见用法,具体以官方文档为准
云资源查询

查实例、存储、账单等云上资源状态。

部署与发布

把部署、重启、回滚这类操作接进对话。

监控与告警

拉取监控指标,异常时让模型帮你判断。

选择建议

选之前先看这几条
按条目字段给出的判断,不替你决定用不用

值得选的地方

  • 资料标注 12 个工具,覆盖面较广,能满足多种调用。
  • 有现成的安装命令,不用自己找入口,照着跑就能起服务。

先想清楚的地方

  • stdio 方式要求本地装好运行时(如 Node.js),换机器要重新装一遍。
  • 使用前要准备好Token对应的凭据,并按最小权限配置。
  • 版本更新与行为细节以官方仓库为准。

更适合

  • 需要在运维云端场景里让模型直接调用外部能力的人。
  • 想先快速试一下、能接受在本地或自有环境跑服务的人。

不太适合

  • 完全不想在本地装环境的人。
  • 不方便管理密钥或第三方授权的人。
  • 需要厂商级 SLA 和技术支持的生产环境。

同类对比

6 个同类
同分类里挑最接近的几条,字段以各自详情页为准
MCP 服务器工具数传输方式部署方式安装命令最后核验
Kiotviet MCP当前 12 stdio · 本地进程 本地部署 有 2026-05-17
lobehub 未标注 stdio · 本地进程 本地部署 有 2026-04-11
TrendRadar 未标注 stdio · 本地进程 本地部署 有 2026-04-13
Ui Tars Desktop 8a825770 未标注 stdio · 本地进程 本地部署 有 2026-05-17
ruflo 未标注 stdio · 本地进程 本地部署 有 2026-04-13
FastGPT 未标注 stdio · 本地进程 本地部署 有 2026-04-11

服务器档案

运维云端
字段来自项目仓库与公开索引,中文说明由本站标注
提供方dehuy69上游标注的维护方 dehuy69
分类运维云端本站按上游分类展示
连接方式stdio · 本地进程客户端在本机拉起子进程,数据不出本机
鉴权方式Token远程服务建议用最小权限凭据
维护方社区 / 第三方核验等级 仅资料核对
包名 / 运行时未标注 · 未标注本地安装时用到的包标识与运行时
部署类型本地部署上游给出的部署形态
最近核验2026-05-17上游最后核验时间

详细介绍

7.5 KB
来自项目仓库与上游目录的原文,未做删改

kiotviet-mcp

MCP server kết nối đến phần mềm KiotViet thông qua API. Được xây dựng bằng FastMCP, stateless - không quản lý phiên của user.

> 📖 English Version | Tiếng Việt

Mô tả

kiotviet-mcp là một Model Context Protocol (MCP) server cho phép AI agents (như Culi) tương tác với KiotViet Public API một cách an toàn. Server này:

  • Stateless: Không quản lý phiên, không lưu trữ token
  • Nhận access_token và retailer từ Culi cho mỗi request
  • Cung cấp các tools để truy vấn và thao tác dữ liệu KiotViet
  • Đơn giản, nhẹ, không có state management

Kiến trúc```

┌─────────────────────────────────────────┐
│ Culi Backend │
│ │
│ 1. User đăng nhập │
│ 2. Lấy client_id, client_secret │
│ 3. Gọi OAuth2 để lấy access_token │
│ POST https://id.kiotviet.vn/connect/token
│ 4. Truyền access_token + retailer │
│ xuống kiotviet-mcp │
└──────────────┬──────────────────────────┘
│
│ MCP Tool Call
│ (access_token, retailer, ...)
▼
┌─────────────────────────────────────────┐
│ kiotviet-mcp (Stateless) │
│ │
│ - Nhận access_token + retailer │
│ - Gọi KiotViet API │
│ - Trả về kết quả │
│ - KHÔNG lưu trữ state │
└──────────────┬──────────────────────────┘
│
│ HTTP Request
│ (Retailer header + Bearer token)
▼
┌─────────────────────────────────────────┐
│ KiotViet Public API │
└─────────────────────────────────────────┘


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

Cấu trúc dự án```

kiotviet-mcp/
├── kiotviet_mcp_server.py # FastMCP server entrypoint
├── kv_client.py # HTTP client cho KiotViet API (stateless)
├── requirements.txt # Dependencies
└── README.md # Tài liệu này


## Sử dụng

### Chạy MCP Server```bash
python kiotviet_mcp_server.py

Hoặc nếu sử dụng với MCP client:```bash
mcp-server kiotviet-mcp


### Flow hoạt động

1. **Culi Backend** lấy `access_token` từ KiotViet OAuth2:```python
# Culi backend
import httpx

TOKEN_URL = "https://id.kiotviet.vn/connect/token"

def get_access_token(client_id: str, client_secret: str) -> str:
data = {
"scopes": "PublicApi.Access",
"grant_type": "client_credentials",
"client_id": client_id,
"client_secret": client_secret,
}
headers = {"Content-Type": "application/x-www-form-urlencoded"}
resp = httpx.post(TOKEN_URL, data=data, headers=headers)
resp.raise_for_status()
return resp.json()["access_token"]
  1. Culi Backend gọi MCP tools với access_token và retailer:```python

Culi backend gọi MCP tool

access_token = get_access_token(client_id, client_secret)
retailer = "taphoaxyz"

Gọi tool qua MCP

result = kv_list_products(
access_token=access_token,
retailer=retailer,
name="áo",
page_size=20
)


3. **kiotviet-mcp** gọi KiotViet API và trả về kết quả

### Các Tools có sẵn

#### Product Tools
- `kv_list_products`: Lấy danh sách sản phẩm
- `kv_get_product`: Lấy chi tiết sản phẩm

#### Customer Tools
- `kv_search_customers`: Tìm kiếm khách hàng
- `kv_get_customer`: Lấy chi tiết khách hàng
- `kv_create_customer`: Tạo khách hàng mới

#### Order Tools
- `kv_list_orders`: Lấy danh sách đơn hàng
- `kv_get_order`: Lấy chi tiết đơn hàng
- `kv_create_order`: Tạo đơn hàng mới

#### Invoice Tools
- `kv_list_invoices`: Lấy danh sách hóa đơn
- `kv_get_invoice`: Lấy chi tiết hóa đơn

#### Category Tools
- `kv_list_categories`: Lấy danh sách nhóm hàng

#### Branch Tools
- `kv_list_branches`: Lấy danh sách chi nhánh

## Ví dụ sử dụng

### Ví dụ 1: Lấy danh sách sản phẩm```python
# Culi backend
access_token = get_access_token(client_id, client_secret)
retailer = "taphoaxyz"

# Gọi MCP tool
products = kv_list_products(
access_token=access_token,
retailer=retailer,
name="áo",
page_size=20
)

Ví dụ 2: Tìm khách hàng```python

customers = kv_search_customers(
access_token=access_token,
retailer=retailer,
contact_number="0123456789"
)


### Ví dụ 3: Tạo đơn hàng```python
order = kv_create_order(
access_token=access_token,
retailer=retailer,
branch_id=1,
purchase_date="2024-01-15",
order_details=[
{
"productId": 123,
"quantity": 2,
"price": 100000
}
],
customer_id=456
)

Đặc điểm

✅ Stateless

  • Không lưu trữ token
  • Không quản lý phiên
  • Mỗi request độc lập

✅ Đơn giản

  • Không cần registry
  • Không cần authorization
  • Chỉ là proxy layer

✅ An toàn

  • Token được quản lý bởi Culi backend
  • MCP không lưu trữ thông tin nhạy cảm
  • Mỗi request có token riêng

✅ Scalable

  • Stateless → dễ scale
  • Không có shared state
  • Có thể chạy nhiều instances

Token Management

Token được quản lý bởi Culi Backend:

  • Culi lấy token từ KiotViet OAuth2
  • Token có thể được cache trong Culi (tùy chọn)
  • Token được truyền xuống MCP cho mỗi request
  • MCP không refresh token (Culi tự refresh nếu cần)

Resources & Prompts

Server cung cấp các resources và prompts để hướng dẫn LLM sử dụng đúng tools:

  • kiotviet://products_schema: Schema cho products API
  • kiotviet://customers_schema: Schema cho customers API
  • kiotviet://orders_schema: Schema cho orders API
  • kiotviet://invoices_schema: Schema cho invoices API
  • kiotviet_assistant_prompt: System prompt hướng dẫn LLM

Phát triển

Thêm tool mới

  1. Tạo function với decorator @mcp.tool
  2. Thêm parameters: access_token: str, retailer: str
  3. Sử dụng _create_client(access_token, retailer) để tạo client
  4. Gọi API thông qua client methods: get(), post(), put(), delete()
  5. Thêm docstring mô tả rõ ràng cho LLM

Testing

Xem hướng dẫn chi tiết trong TESTING.md để biết cách:
- Lấy access token
- Xác định retailer
- Test các tools
- Troubleshooting

Ví dụ test nhanh:```bash

Test với access_token và retailer

python -c "
from kiotviet_mcp_server import kv_list_products
result = kv_list_products(
access_token='your_token',
retailer='your_retailer',
page_size=10
)
print(result)
"
```

So sánh với kiến trúc cũ

Kiến trúc cũ (Multi-tenant với Registry)

  • ❌ Phức tạp: Cần registry, authorization
  • ❌ Stateful: Lưu trữ token, quản lý phiên
  • ❌ Culi phải đăng ký account trước

Kiến trúc mới (Stateless)

  • ✅ Đơn giản: Chỉ là proxy
  • ✅ Stateless: Không lưu trữ state
  • ✅ Linh hoạt: Culi tự quản lý token

License

MIT

Liên hệ

Dự án này là một phần của hệ sinh thái Culi - AI agent hỗ trợ kế toán cho hộ kinh doanh.

常见问题

7 问
答案由本站依据条目字段整理,不引用上游原文
Kiotviet MCP 怎么安装?

在客户端按下面的安装命令接入:pip install -r requirements.txt。装完在客户端配置里引用同一个包或端点。

Kiotviet MCP 怎么在客户端里配置?

它的传输方式未标注,在客户端 MCP 配置里按官方文档填写启动命令和参数,保存后重启客户端生效。

Kiotviet MCP 收费吗?

本站不代收费用,也没有标注具体价格。是否收费取决于服务本身和背后的接口额度,正式使用前按官方说明确认。

Kiotviet MCP 需要 API Key 吗?

资料标注需要Token认证,使用前准备好对应凭据,并按最小权限配置。

Kiotviet MCP 能提供哪些能力?

资料显示约 12 个工具;能力标签包括 API代理、Python、数据操作。具体工具清单以官方文档为准。

Kiotviet MCP 需要什么运行环境?

属于本地进程,需要在本机装好运行环境。

Kiotviet MCP 是本地还是远程?

它是本地进程(stdio),由客户端在本机拉起。传输方式为stdio · 本地进程。

热门专题

按标签挑服务器
全部专题 →

服务器信息以作者仓库与官方文档为准;分类、传输方式与鉴权方式的中文说明为中文整理,最近核验 2026-05-17。