·

Airtable MCP với Claude Code CLI and VS Code

Cài đặt Airtable MCP trong Claude Code CLI and VS Code để AI agent có thể đọc và cập nhật base và record ngay trong trình soạn thảo.

Claude Code là coding agent chạy trực tiếp trong terminal (và extension VS Code), rất phù hợp để gắn Airtable MCP vào quy trình quản lý requirement vì bạn đang code và đang cần cập nhật trạng thái ngay trong cùng một phiên làm việc — không cần chuyển tab sang browser. Bài này hướng dẫn cài đặt Airtable MCP cho cả Claude Code CLI và VS Code extension, cách query/filter record ngay từ terminal, cách tạo/cập nhật requirement record dựa trên code change thật, và cách viết prompt an toàn cho các thao tác ghi dữ liệu số lượng lớn.

Cài Đặt Và Kết Nối Airtable MCP Vào Claude Code

Claude Code hỗ trợ MCP server qua lệnh claude mcp add hoặc file cấu hình project .mcp.json. Với Airtable, cách nhanh nhất là dùng package Node có sẵn.

Cách 1 — thêm qua CLI (áp dụng cho user hiện tại, mọi project):

claude mcp add airtable --scope user \
  -- npx -y airtable-mcp-server

Sau đó set biến môi trường token — Claude Code sẽ đọc từ env khai báo trong config, nên cách sạch nhất là sửa trực tiếp file config vừa tạo:

claude mcp list

Cách 2 — khai báo trực tiếp trong .mcp.json ở root project (khuyên dùng cho team, để mọi người dùng chung cấu hình, chỉ khác token cá nhân):

{
  "mcpServers": {
    "airtable": {
      "command": "npx",
      "args": ["-y", "airtable-mcp-server"],
      "env": {
        "AIRTABLE_API_KEY": "${AIRTABLE_API_KEY}"
      }
    }
  }
}

Với cách này, mỗi dev tự export biến môi trường riêng trong .env cá nhân (không commit), Claude Code sẽ tự thay ${AIRTABLE_API_KEY} khi khởi động server:

echo 'AIRTABLE_API_KEY=patXXXXXXXXXXXXXX.xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx' >> .env
source .env

Với VS Code extension (Claude Code): extension dùng chung cấu hình .mcp.json của project, không cần setup riêng — mở Command Palette, chạy Claude Code: Restart MCP Servers sau khi sửa file config để nạp lại.

Kiểm tra kết nối thành công bằng lệnh đơn giản trong phiên Claude Code:

List all Airtable bases I have access to.

Nếu trả về đúng tên base bạn kỳ vọng (ví dụ "Product Roadmap"), kết nối đã ổn.

Mẹo: Chạy claude mcp add với --scope project thay vì user nếu bạn muốn config chỉ áp dụng cho repo hiện tại — tránh trường hợp Airtable MCP tự động available ở mọi project khác trên máy, gây rối khi bạn làm nhiều project khác nhau cùng lúc.

Query Base Và Filter Record Ngay Trên Terminal

Sức mạnh thật của việc gắn Airtable vào Claude Code CLI nằm ở việc bạn có thể hỏi bằng ngôn ngữ tự nhiên mà không cần nhớ cú pháp filterByFormula của Airtable.

Ví dụ prompt truy vấn thực tế:

Trong base "Product Roadmap", table "Requirements", liệt kê tất cả
record có Status = "In Progress" và Priority = "High".
Hiển thị dạng bảng gồm Title, Assignee, Due Date.

Claude Code sẽ tự dịch yêu cầu này thành lệnh gọi tool list_records với filterByFormula tương đương:

AND({Status} = "In Progress", {Priority} = "High")

Bạn cũng có thể yêu cầu agent tự viết công thức filter phức tạp hơn mà bạn không rành cú pháp Airtable formula:

Tìm các requirement chưa có Assignee, được tạo trong 7 ngày gần nhất,
và Status khác "Done".

Với truy vấn nhiều điều kiện lồng nhau, nên yêu cầu agent in ra công thức filterByFormula nó dùng trước khi chạy — vừa để bạn học cú pháp Airtable formula, vừa để double-check logic đúng ý.

Khi dữ liệu lớn (hàng nghìn record), nhắc agent luôn dùng pageSize hợp lý (Airtable mặc định trả tối đa 100 record/trang) và tự động page qua offset nếu cần tổng hợp toàn bộ, tránh trường hợp agent chỉ đọc 100 record đầu rồi kết luận sai số liệu tổng.

Mẹo: Với các câu hỏi thống kê ("bao nhiêu requirement đang quá hạn?"), luôn yêu cầu agent nêu rõ đã quét bao nhiêu record tổng cộng trong câu trả lời — cách này giúp bạn phát hiện ngay nếu agent chỉ đọc một trang mà tưởng là toàn bộ dữ liệu.

Tạo Và Cập Nhật Requirement Record Từ Code Changes

Đây là workflow giá trị nhất khi kết hợp Airtable MCP với một coding agent: agent vừa đọc được diff code, vừa viết được vào Airtable trong cùng một phiên.

Tạo requirement record từ một feature mới đang code:

Tôi vừa viết xong branch feature/sso-login (xem git diff hiện tại).
Tạo record mới trong table "Requirements" của base "Product Roadmap":
- Title: "SSO Login via Google Workspace"
- Description: tóm tắt từ code diff, nêu rõ các thay đổi chính
- Status: "In Review"
- Linked PR: (số PR nếu đã tạo, nếu chưa thì để trống)
- Effort: ước lượng story point dựa trên số file/dòng thay đổi

Cập nhật record khi PR merge (chạy sau khi merge, thủ công hoặc trong hook):

PR #482 "Add SSO login" vừa merge vào main.
Tìm record trong table "Requirements" có tiêu đề chứa "SSO Login",
cập nhật:
- Status = "Done"
- Merged Date = ngày hôm nay
- Linked PR = "482"

Một pattern rất hữu ích cho team dùng trunk-based development: gắn convention trong PR description (ví dụ dòng Airtable-Record: rec1a2B3c4D5e6F7g) để agent match record bằng recordId chính xác tuyệt đối thay vì match mờ theo tên — tránh trường hợp có hai requirement trùng tên bị update nhầm.

Đọc PR description hiện tại, tìm dòng "Airtable-Record: recXXXX",
dùng recordId đó để update trực tiếp qua get_record rồi update_records,
không tìm theo tên Title.

Mẹo: Luôn thêm convention Airtable-Record: <recordId> vào template PR description của team ngay từ đầu — chi phí gần như bằng không, nhưng giúp mọi lần đồng bộ về sau chính xác 100% thay vì dựa vào match tên dễ nhầm.

Mẫu Prompt An Toàn Cho Các Thao Tác Bulk Trên Record

Thao tác hàng loạt (tạo/sửa/xóa nhiều record cùng lúc) là nơi rủi ro cao nhất khi giao cho AI agent — một câu prompt mơ hồ có thể khiến agent sửa nhầm hàng trăm record trước khi bạn kịp phản ứng. Dưới đây là các pattern prompt giúp giảm rủi ro này.

Pattern 1 — luôn yêu cầu "preview trước, confirm sau":

Tìm tất cả record trong table "Requirements" có Status = "Backlog"
và Created Date trước 2026-01-01.
Trước tiên chỉ LIỆT KÊ các record này (Title + recordId), CHƯA sửa gì.
Sau khi tôi xác nhận, mới cập nhật Status = "Archived".

Cách này buộc agent chia task thành hai bước rõ ràng, cho bạn cơ hội chặn lại nếu số lượng match nhiều hơn dự kiến (dấu hiệu công thức filter sai).

Pattern 2 — giới hạn số lượng record tối đa mỗi lần chạy:

Cập nhật Status = "Done" cho các record có Linked PR khớp với PR #482.
Nếu số record khớp nhiều hơn 3, DỪNG lại và báo cho tôi biết,
không tự động update.

Giới hạn này đóng vai trò như một "circuit breaker" — khi công thức filter tình cờ quá rộng (bug logic, hoặc dữ liệu bẩn), agent tự dừng thay vì âm thầm sửa sai hàng loạt.

Pattern 3 — luôn yêu cầu batch nhỏ khi tạo record số lượng lớn:

Từ file requirements-import.csv, tạo record cho mỗi dòng vào
table "Requirements". Batch 10 record mỗi lần gọi create_records,
báo tiến độ sau mỗi batch, dừng ngay nếu gặp lỗi và không tự retry
quá 2 lần liên tiếp.

Pattern 4 — không bao giờ giao xóa record hàng loạt không giám sát:

KHÔNG dùng delete_records cho tác vụ này. Nếu cần loại bỏ record,
chỉ cập nhật Status = "Archived", giữ nguyên dữ liệu.

Với xóa dữ liệu, gần như luôn nên thay bằng "soft delete" (đổi status) — Airtable không có trash/undo dễ dùng như file system, một lệnh delete_records sai phạm vi là mất dữ liệu thật.

Mẹo: Với mọi tác vụ bulk chạm > 10 record, luôn thêm câu "nếu số record khớp nhiều hơn X thì dừng và hỏi lại tôi" vào prompt — một dòng này là rào chắn rẻ nhất chống lại lỗi filter formula sai phạm vi.

Mẹo Thực Chiến

  • Dùng .mcp.json ở project root (không phải config user global) khi làm việc theo team, để mọi người review được cấu hình MCP qua code review như bất kỳ file config khác.
  • Luôn chạy thử list_records với pageSize nhỏ (ví dụ 5) trước khi giao task tổng hợp số liệu lớn, để chắc agent hiểu đúng schema field trước khi xử lý hàng loạt.
  • Convention Airtable-Record: <recordId> trong PR description/commit message là cách rẻ nhất để đồng bộ hai chiều chính xác giữa Git và Airtable.
  • Không giao delete_records cho agent chạy trong workflow tự động không giám sát — luôn thiết kế bằng soft-delete qua field Status.
  • Restart MCP server (Claude Code: Restart MCP Servers trong VS Code, hoặc khởi động lại session CLI) sau mỗi lần sửa token hoặc scope, vì client thường cache connection cũ.

Mẹo: Nếu team dùng cả Claude Code CLI và VS Code extension, hãy đồng bộ một file .mcp.json duy nhất trong repo — tránh tình trạng hai môi trường trỏ tới hai token/base khác nhau khiến kết quả tra cứu không nhất quán giữa các thành viên.

Tiếp Airtable MCP với OpenCode