Cài đặt InnerSheet

Trình cài đặt thêm gì vào cấu hình

Đây là mục trình cài đặt gộp vào mcpServers (trên Linux thì in ra). uv run đọc danh sách thư viện khai báo ngay trong server.py, nên không có môi trường ảo nào phải tự quản lý.

{
  "mcpServers": {
    "innersheet": {
      "command": "uv",
      "args": ["run", "/path/to/innersheet/server.py"],
      "env": {
        "GOOGLE_OAUTH_CLIENT_SECRETS": "/path/to/innersheet/client_secret.json"
      }
    }
  }
}

Thiết lập Google Cloud — bước ai cũng làm một lần

InnerSheet đăng nhập Google Sheets bằng chính tài khoản của bạn, nên Google cần biết ứng dụng này tồn tại. Miễn phí, không cần thẻ tín dụng. Lần đầu hãy dành khoảng năm phút.

Console bản mới gom phần OAuth vào Google Auth Platform (các tab Branding, Audience, Clients); bản cũ gọi là OAuth consent screen. Bên dưới ghi cả hai tên.

1. Tạo một project

   Vào console.cloud.google.com, đăng nhập bằng tài khoản Google sở hữu các sheet, và tạo project mới. Tên nào cũng được — innersheet là ổn.

2. Bật hai API

   Mở APIs & Services → Library và bật Google Sheets API và Google Drive API. Drive chỉ dùng để tìm bảng tính theo tên. Bỏ qua bước này sẽ gặp lỗi "API has not been used in project".

3. Cấu hình màn hình đồng ý

   Mở Google Auth Platform → Branding (bản cũ: APIs & Services → OAuth consent screen). Đặt tên ứng dụng (InnerSheet) và email của bạn, chọn đối tượng External, rồi lưu. Dùng cá nhân thì không cần logo hay chính sách riêng tư.

4. Chọn ai được đăng nhập: publish, hoặc thêm mình làm test user

   Ứng dụng mới luôn ở trạng thái Testing. Mở Audience và chọn một trong hai:

   Lựa chọn	Cách làm	Đánh đổi
   Publish ứng dụng Nên dùng	Audience → Publish app → xác nhận In production.	Đăng nhập giữ được lâu dài. Bạn sẽ thấy màn “Google hasn't verified this app” một lần — bình thường với project cá nhân, không cần xác minh.
   Giữ ở Testing	Audience → Test users → Add users → thêm Gmail bạn sẽ dùng để đăng nhập.	Google làm hết hạn đăng nhập sau mỗi 7 ngày, nên tuần nào cũng phải đăng nhập lại.

   Không làm cái nào sẽ gặp Error 403: access_denied. Giữ ở Testing là lý do của lỗi invalid_grant hằng tuần.

5. Tạo OAuth client loại Desktop

   Mở Google Auth Platform → Clients → Create client (bản cũ: Credentials → Create Credentials → OAuth client ID). Chọn loại Desktop app — không chọn “Web application”, vì sẽ gây lỗi redirect_uri_mismatch. Tải file JSON về.

6. Lưu file cạnh server

   Đổi tên file thành client_secret.json và đặt trong thư mục innersheet — đúng đường dẫn trình cài đặt đã cấu hình. Đừng commit lên git hay chia sẻ; file đã nằm trong .gitignore kèm theo.

7. Chạy lần đầu: đăng nhập một lần

   Lần đầu một công cụ chạy, trình duyệt mở trang đăng nhập Google. Đăng nhập và chấp nhận quyền. Token được lưu tại ~/.config/innersheet/token.json và tự làm mới.

   Gặp “Google hasn't verified this app”? Bình thường với project bạn tự tạo: nhấn Advanced, rồi Go to InnerSheet (unsafe).

Bảng cấu hình

InnerSheet được cấu hình bằng biến môi trường. Đặt chúng trong khối env của cấu hình client (hoặc -e KEY=value với claude mcp add), rồi khởi động lại client.

Tham số dòng lệnh

Ví dụ: chỉ đọc, chỉ hai bảng tính

"env": {
  "GOOGLE_OAUTH_CLIENT_SECRETS": "/path/to/innersheet/client_secret.json",
  "SHEETS_MCP_READ_ONLY": "1",
  "SHEETS_MCP_ALLOWED_SPREADSHEETS": "1AbCdEfGhIjK,1ZyXwVuTsRqP"
}

ID bảng tính là phần trong URL nằm giữa /d/ và /edit. Sau khi bật hoặc tắt chế độ chỉ đọc, hãy xóa token.json một lần để Google cấp token với quyền tương ứng.

Cài thủ công (không dùng trình cài đặt)

Nếu bạn muốn thấy từng bước, cách thủ công rất ngắn. Bạn cần Python 3.10 trở lên.

# macOS / Linux
python3 -m venv .venv
.venv/bin/pip install -r requirements.txt

# Windows (PowerShell)
py -3 -m venv .venv
.venv\Scripts\pip install -r requirements.txt

File cấu hình cho từng client có ở trang AI Clients.

Kiểm tra kết nối

Sau khi khởi động lại AI client, chạy lần lượt các kiểm tra này. Dừng ở bước đầu tiên bị lỗi và tra lỗi đó ở trang Xử lý lỗi.

1. Trong terminal: uv run /path/to/innersheet/server.py --version phải in ra innersheet 2.0.0. Nếu không, lỗi nằm ở bước cài chứ không phải ở client.
2. "List my spreadsheets" — AI phải trả lời bằng tên các sheet thật. Nếu không tìm thấy gì, bước đăng nhập Google chưa xong.
3. "Read A1:D10 from <tên sheet>" — kiểm tra giá trị khớp với những gì bạn thấy trên trình duyệt.
4. "Upsert today's row in my daily report, dry run only" — AI phải mô tả những gì nó sẽ ghi, mà không ghi gì cả.