Kamai MCP

npx add-mcp 'https://mcp.kamai.io/mcp'

kamai-mcp

Máy chủ MCP của Kamai: các công cụ và tiện ích MCP Apps cho các dự án bản thiết kế xây dựng, bản thiết kế và bóc tách khối lượng của Kamai. Nó chạy dựa trên API MCP của Kamai và xác thực các mã truy cập do máy chủ ủy quyền OAuth của Kamai cấp. Nó không lưu giữ bí mật nào của Kamai.

Công cụ

Công cụ	Chức năng
view_projects	Bảng điều khiển tương tác hiển thị các dự án và bản thiết kế của người dùng
list_blueprints	Các bản thiết kế được nhóm theo dự án, kèm mã định danh và trạng thái sẵn sàng
view_blueprint	Một trang bản thiết kế với các hình dạng bóc tách được vẽ chồng lên trên
view_takeoff	Khối lượng bóc tách đã đo dưới dạng bảng có thể sắp xếp
list_elements	Các hàng theo từng phần tử (phòng, tường, cửa, cửa sổ, đối tượng) kèm đường viền
list_folders	Các thư mục chú giải của một bản thiết kế
download_plan	Bản PDF của bản thiết kế đã xử lý với các phần tử được phát hiện được tô sáng, dưới dạng liên kết tải xuống tạm thời
update_elements, move_elements, create_folder	Đổi tên, đổi màu và chuyển thư mục cho các phần tử; tạo một thư mục
set_opening_height	Lưu chiều cao do người dùng khai báo hoặc nhãn cửa/cửa sổ trên các mảnh mở bề mặt tường
create_project, update_project	Tạo hoặc đổi tên một dự án
list_jobs, get_job, cancel_job	Các tác vụ xử lý của một dự án
view_upload	Bảng tải lên cho bản PDF bản thiết kế
ingest_blueprint_from_chat	Nhập bản PDF đính kèm trong tin nhắn ChatGPT (chỉ dành cho ChatGPT)
open_kamai	Mở ứng dụng Kamai trong một bảng điều khiển

Với KAMAI_QUERY_TOOLS=on (xem bên dưới):

Công cụ	Chức năng
count_elements	Số lượng và tổng theo danh mục Kamai (cửa, cửa sổ, tường, phòng ướt…), được nhóm và cộng trong cơ sở dữ liệu
find_elements	Các phần tử riêng lẻ kèm loại, thư mục, nhãn, hướng và số đo
calculate_wall_surface_area	Diện tích tường thực (sơn hoặc trát) của các phòng
render_table	Bảng điều khiển dạng bảng có các hàng tô sáng phần tử tương ứng trên mặt bằng
set_scale	Đặt tỷ lệ bản vẽ của một bản thiết kế

list_blueprints cũng nhận include_inventory (với project_id): nội dung của từng bản thiết kế.

list_projects, get_project, get_blueprint, request_blueprint_upload, finalize_blueprint_upload và cùng với các công cụ truy vấn get_table_row_elements và get_element_outlines chỉ dành cho ứng dụng: chỉ các tiện ích gọi được, không quảng bá cho mô hình.

Chạy cục bộ với khóa API của bạn

Cách nhanh nhất để chạy máy chủ này với dữ liệu Kamai của riêng bạn là chế độ cục bộ: máy chủ khởi động máy chủ, giao tiếp qua stdio và thông tin xác thực là khóa API cá nhân từ Kamai (API Keys trong ứng dụng Kamai) thay vì OAuth.

bun install
bun run build:widgets
KAMAI_API_KEY=... MCP_API_BASE_URL=https://mcp-api.kamai.io bun run local

Claude Code:

claude mcp add --env KAMAI_API_KEY=... --env MCP_API_BASE_URL=https://mcp-api.kamai.io \
  --transport stdio kamai -- bun /path/to/kamai-mcp/src/local.ts

Claude Desktop (claude_desktop_config.json):

{ "mcpServers": { "kamai": {
    "command": "bun", "args": ["/path/to/kamai-mcp/src/local.ts"],
    "env": { "KAMAI_API_KEY": "...", "MCP_API_BASE_URL": "https://mcp-api.kamai.io" } } } }

Khóa được dùng làm bearer cho mọi lời gọi API; các công cụ chạy với tư cách chủ sở hữu khóa. Thêm KAMAI_QUERY_TOOLS=on vào môi trường cho các công cụ truy vấn.

Chạy máy chủ HTTP

bun install
cp .env.example .env
bun run dev

Các giá trị trong .env.example là chỗ giữ chỗ: đặt MCP_PUBLIC_URL và MCP_AUTH_ISSUER thành đường hầm của bạn và một máy chủ ủy quyền có thể truy cập trước khi khởi động, nếu không mọi yêu cầu sẽ bị từ chối với invalid_token.

Biến	Ý nghĩa
PORT	Cổng lắng nghe, mặc định 8006
MCP_PUBLIC_URL	URL mà máy chủ gọi và yêu cầu mã (resource trong khám phá); một đường hầm, không phải localhost
MCP_AUTH_ISSUER	Nơi phát hành mã truy cập, được so khớp từng byte với iss của mã
MCP_AUTH_JWKS_URI	Tùy chọn. Mặc định là {MCP_AUTH_ISSUER}/jwks.json
MCP_API_BASE_URL	URL cơ sở API MCP của Kamai, https://mcp-api.kamai.io. Cũng là đối tượng mà mã truy cập phải mang
MCP_ACCEPTED_AUDIENCES	Tùy chọn, danh sách đối tượng phân tách bằng dấu phẩy, cho quá trình chuyển đổi. Mặc định là MCP_API_BASE_URL
KAMAI_API_KEY	Chỉ chế độ cục bộ: khóa API cá nhân mà các công cụ chạy với tư cách
KAMAI_APP_ORIGINS	Tùy chọn, danh sách nguồn gốc bổ sung phân tách bằng dấu phẩy mà open_kamai có thể nhúng; nguồn gốc đầu tiên trở thành mặc định
KAMAI_QUERY_TOOLS	on đăng ký các công cụ truy vấn. https://mcp-api.kamai.io phục vụ chúng; tắt nó khi dùng API trả lời /v1/vocabulary với 404
KAMAI_MCP_NO_INSTRUCTIONS	1 bỏ hướng dẫn máy chủ ra, như claude.ai làm, để kiểm tra riêng các mô tả công cụ

API MCP và máy chủ ủy quyền do Kamai vận hành, nên chạy máy chủ HTTP từ đầu đến cuối cần quyền truy cập cả hai. Một máy chủ MCP chỉ thực sự kiểm thử được với một máy chủ thực và máy chủ chỉ có thể truy cập URL HTTPS công khai, nên phát triển chế độ HTTP nghĩa là chạy sau một đường hầm và trỏ MCP_PUBLIC_URL vào đó.

bun run dev xây dựng các tiện ích trước: máy chủ phục vụ HTML đã xây dựng từ dist/widgets/, không phải mã nguồn React, nên hãy xây dựng lại sau khi chạm vào bất kỳ thứ gì dưới src/widgets/app/.

Các tiện ích dùng React, TypeScript, Vite, Tailwind CSS, DaisyUI và Lucide. Vite tạo một tài nguyên HTML khép kín cho mỗi tiện ích, nên không cần lưu trữ gì thêm.

Bản dựng cục bộ yêu cầu Bun 1.3.3 và Node.js 22.12 trở lên.

Bố cục

src/index.ts       Máy chủ HTTP, siêu dữ liệu tài nguyên được bảo vệ OAuth, truyền tải MCP
src/local.ts       Điểm vào stdio cho chế độ cục bộ (khóa API cá nhân)
src/auth.ts        Xác minh mã Bearer (thử thách RFC 9728)
src/server.ts      Đăng ký công cụ và tài nguyên
src/api.ts         Máy khách cho API MCP của Kamai
src/elements.ts    Phân trang, lọc và ngân sách kết quả list_elements
src/errors.ts      Văn bản mà lời gọi công cụ thất bại hiển thị cho mô hình
src/query/         Công cụ truy vấn: mô tả, từ vựng, bộ lọc, ngân sách, hợp đồng
src/widgets/       Tài nguyên tiện ích, siêu dữ liệu CSP và mã nguồn tiện ích React
scripts/           Bản dựng tiện ích (thoát & để Open WebUI có thể nhúng
                   tiện ích); check-routes và check-vocabulary với API trực tiếp
scripts/open-webui/
                   Trợ giúp Open WebUI: một công cụ open_kamai, một tập lệnh máy chủ
                   chế độ hiển thị, một bản demo cầu nối cục bộ

Quyền riêng tư và hỗ trợ

• Chính sách quyền riêng tư: https://kamai.io/privacy-policy
• Hỗ trợ: https://kamai.io/support hoặc contact@kamai.io

Đóng góp

Xem CONTRIBUTING.md. Các vấn đề bảo mật gửi đến địa chỉ trong SECURITY.md, không gửi đến trình theo dõi vấn đề.

Giấy phép

Apache-2.0. Bản quyền 2026 Kamai Enterprises LTD.

Tên và logo Kamai là nhãn hiệu của Kamai Enterprises LTD và không được bao phủ bởi giấy phép.