Skip to main content
Glama

async-sheet-mcp

공유 구글 시트 한 장을, 떨어져 일하는 소규모 팀과 그들의 AI 에이전트가 함께 쓰는 "비동기 인계 창구"로 만드는 MCP 서버.

An MCP server that turns a shared Google Sheet issue list into an asynchronous handoff channel for small, remote teams — each teammate's AI agent reads open items, does the work, and writes a dated reply only into its own column.

python mcp license


목차

  1. 어떤 문제를 푸는가

  2. 해결 방식

  3. 기능

  4. 동작 구조

  5. 시트 규약

  6. 설치와 등록

  7. 설정값

  8. 사용 예

  9. 설계에서 신경 쓴 점

  10. 한계

  11. 개발


Related MCP server: handoff

1. 어떤 문제를 푸는가

하드웨어(펌웨어) 개발자 1명과 서버 개발자 1명이 서로 다른 장소·다른 시간에 일하는 IoT 프로젝트에서 출발했습니다. 두 사람은 실시간으로 대화하기 어려워, 구글 시트의 문제점 목록에 요청을 올리고 답을 적는 방식으로 협업했습니다.

두 사람 모두 AI 코딩 에이전트(Claude Code)를 쓰기 시작하자 병목이 드러났습니다.

겪은 일

왜 문제였나

시트를 엑셀로 내려받아 AI 에게 붙여넣기

매번 손이 가고, 붙여넣은 순간부터 낡은 사본이 됨

작업이 끝나면 회신 문구를 사람이 시트에 옮겨 적기

빠뜨리거나 다른 칸에 적는 실수, "어디까지 됐는지" 서로 모름

회신이 한 칸에서 덮어써짐

누가 언제 무슨 말을 했는지 이력이 사라짐

이슈 트래커(Jira 등) 도입 검토

두 명에게는 과하고, 상대는 이미 시트에 익숙함

필요했던 것은 새 도구가 아니라, 이미 쓰는 시트를 AI 가 직접 읽고 규칙대로 답하게 하는 얇은 연결고리였습니다.

2. 해결 방식

  • 각자의 PC 에서 이 MCP 서버를 띄우고, AI 에이전트가 시트를 직접 읽고 씁니다.

  • 같은 코드를 쓰되 역할(환경 변수) 만 다르게 줍니다. 서버 담당의 에이전트는 비고 칸에, 단말 담당의 에이전트는 보조 설명 칸에만 씁니다.

  • 회신은 지우지 않고 [9/30 서버] … 처럼 날짜·역할 머리표를 붙여 아래에 쌓습니다. 칸 하나가 그대로 대화 이력이 됩니다.

  • 사람이 하는 말은 이 정도로 줄어듭니다.

"시트 열린 항목 읽고 작업 시작해"      → 읽기 → 코드 수정 → 확인 → 회신 초안 → 시트에 기록
"13번 지금 어디까지 됐어?"             → 그 행의 이력을 읽고 요약
"단말 쪽에 물어볼 것 3개 시트에 올려"  → 새 행 3개 등록

3. 기능

도구

하는 일

쓰기

list_issues(status="open")

끝나지 않은 항목 목록. "all" 이나 특정 상태값("재등록")으로도 조회. 긴 칸은 잘라서 토큰 절약

get_issue(no)

한 건 전체 + 연결탭(상세 설명 탭)의 내용까지 한 번에

read_tab(name) / list_tabs()

임의 탭을 텍스트로 / 탭 목록

append_comment(no, text)

내 칸 끝에 [M/D 역할] text 를 새 줄로 덧붙임. 칸 줄바꿈과 행 높이까지 맞춤

✔

set_status(no, status)

상태 칸 변경(등록 → 확인중 → 完 등)

✔

add_issue(mode, problem, …)

맨 아래 새 행(다음 번호·오늘 날짜 자동) — 문제 등록, 상대에게 질문

✔

  • 역할 분리: 내 칸과 상대 칸을 설정으로 나눠, 에이전트가 상대의 글을 건드리지 않습니다.

  • 에이전트 안내문 내장: 서버가 접속한 에이전트에게 "열린 항목부터 본다 · 쓰기 전에 문구를 보여 준다 · 비밀값은 적지 않는다 · 상대 칸은 쓰지 않는다"를 직접 알려 줍니다(MCP instructions). 프롬프트를 매번 쓰지 않아도 규칙이 따라옵니다.

  • 읽기 전용 점검: async-sheet-mcp --check 로 시트에 손대지 않고 연결·권한을 확인합니다.

4. 동작 구조

flowchart LR
    subgraph A[담당자 A의 PC — 역할: 서버]
        CA[AI 에이전트<br/>Claude Code] <-->|stdio| MA[async-sheet-mcp<br/>내 칸 = 비고]
    end
    subgraph B[담당자 B의 PC — 역할: 단말]
        CB[AI 에이전트] <-->|stdio| MB[async-sheet-mcp<br/>내 칸 = 보조 설명]
    end
    MA <-->|Google Sheets API<br/>서비스 계정| S[(공유 구글 시트<br/>문제점 목록)]
    MB <-->|Google Sheets API| S
    H[사람] -.->|브라우저로 그대로 사용| S
  • 표준 입출력(stdio)으로만 통신합니다. 포트를 열지 않고, 별도 서버·DB 가 없습니다. 시트가 곧 저장소입니다.

  • 사람은 지금까지처럼 브라우저에서 시트를 봅니다. 에이전트가 쓴 회신도 같은 칸에 보입니다.

sequenceDiagram
    participant B as 담당자 B (단말)
    participant S as 공유 시트
    participant A as 담당자 A의 에이전트 (서버)
    B->>S: 15번 등록 — "통신이 끊기면 소등으로 집계해 주세요"
    Note over S: 상태 = 등록
    A->>S: list_issues() — 열린 항목 읽기
    A->>A: 코드 수정 · 시험
    A->>S: append_comment(15, "끊기면 소등으로 표시·집계하도록 고침. 배포 후 확인 부탁")
    Note over S: 비고 = [9/30 서버] …
    B->>S: 확인 후 상태를 完 으로

5. 시트 규약

표 한 장이면 됩니다. 첫 칸이 No. 인 행을 헤더로 인식하므로 표 위에 제목·범례 행이 있어도, 열 순서가 달라도 동작합니다.

No.

발생 일자

모델

모드

문제점

연결탭

보조 설명

상태

비고

15

2026-09-30

서버

상태

[문제] 통신이 끊겨도 점등으로 집계됨[대책] 끊기면 소등으로

등록

16

2026-09-30

서버

웹

[문제] 폰에서 접속하면 401

16번

[10/1 단말] 로그인 화면 확인

完

[9/30 서버] 로그인 화면으로 바꿈. 배포 후 확인 부탁

열

쓰임

No.

행 번호(필수, 헤더 인식 기준)

상태

list_issues 필터, set_status 대상

연결탭

긴 설명·그림을 따로 둔 탭 이름. get_issue 가 함께 읽음

내 칸 / 상대 칸

기본 비고 / 보조 설명. 설정으로 바꿈

발생 일자 모델 모드 문제점

add_issue 가 채우는 칸(없는 열은 건너뜀)

열 이름은 공백·줄바꿈을 무시하고 비교합니다(발생⏎일자 = 발생일자).

6. 설치와 등록

준비 (한 번)

  1. Google Cloud 에서 서비스 계정을 만들고 JSON 키를 받습니다. 프로젝트에 Google Sheets API 를 켭니다.

  2. 시트 [공유] 에 서비스 계정 이메일을 편집자로 추가합니다.

  3. 키 파일은 저장소 밖에 둡니다(예: C:\keys\).

설치

git clone https://github.com/masterjms/async-sheet-mcp.git
cd async-sheet-mcp
python -m venv .venv
.venv/Scripts/python -m pip install -e .        # macOS/Linux: .venv/bin/python

연결 점검 (읽기만)

$env:GOOGLE_APPLICATION_CREDENTIALS="C:\keys\my-service-account.json"
$env:SHEET_ID="<스프레드시트 ID>"; $env:SHEET_TAB="문제점"; $env:PYTHONUTF8="1"
.venv\Scripts\async-sheet-mcp --check

Claude Code 에 등록 — 역할만 바꿔 각자 등록합니다.

# 담당자 A (서버)
claude mcp add issue-sheet --scope user `
  -e PYTHONUTF8=1 `
  -e "GOOGLE_APPLICATION_CREDENTIALS=C:\keys\my-service-account.json" `
  -e SHEET_ID=<스프레드시트 ID> -e SHEET_TAB=문제점 `
  -e "SHEET_PROJECT=가로등 관제" -e SHEET_ROLE=서버 `
  -e SHEET_MY_COLUMN=비고 -e "SHEET_PEER_COLUMN=보조 설명" `
  -- "C:\path\to\async-sheet-mcp\.venv\Scripts\async-sheet-mcp.exe"

# 담당자 B (단말) — 역할과 칸만 반대로
#   -e SHEET_ROLE=단말 -e "SHEET_MY_COLUMN=보조 설명" -e SHEET_PEER_COLUMN=비고

새 세션을 열면 도구가 보입니다. 시트가 여러 개면 이름만 바꿔 여러 번 등록하면 됩니다(같은 코드, 다른 환경 변수).

7. 설정값

환경 변수

기본

설명

GOOGLE_APPLICATION_CREDENTIALS

(필수)

서비스 계정 JSON 키 경로

SHEET_ID

(필수)

스프레드시트 ID (/d/ 와 /edit 사이)

SHEET_TAB

문제점

문제점 표가 있는 탭

SHEET_PROJECT

프로젝트 이름. 에이전트 안내문에 들어가 여러 시트를 구분

SHEET_ROLE

서버

이 PC 의 역할 = 회신 머리표 [M/D 역할]

SHEET_MY_COLUMN

비고

내가 회신을 적는 열

SHEET_PEER_COLUMN

보조 설명

상대의 열 — 쓰지 않음

SHEET_DONE

完,완료,사양

끝난 것으로 보는 상태값

SHEET_UTC_OFFSET

9

날짜 머리표의 시간대

8. 사용 예

사용자  시트에 새로 올라온 것 있어?
에이전트 (list_issues) 열린 항목 4건입니다.
         15 [등록] 통신이 끊겨도 점등으로 집계됨
         16 [등록] 폰에서 접속하면 401
         13 [재등록] 지도 핀이 작아 잘 안 보임 …

사용자  15번이랑 16번 처리해 줘.
에이전트 (get_issue ×2 → 코드 수정 → 시험)
         고쳤습니다. 시트에는 이렇게 적겠습니다.
         15: 끊기면 마지막 보고와 관계없이 소등으로 표시·집계합니다.
         16: 브라우저 기본 로그인 창 대신 로그인 화면으로 바꿨습니다. 배포 후 확인 부탁드립니다.

사용자  응 적어.
에이전트 (append_comment ×2) 비고 칸에 [9/30 서버] 로 기록했습니다.

9. 설계에서 신경 쓴 점

  • 기존 습관을 바꾸지 않는다 — 새 트래커를 들이지 않고 이미 쓰던 시트를 그대로 씁니다. AI 를 쓰지 않는 사람도 같은 시트로 계속 일할 수 있습니다.

  • 칸 소유권 — 에이전트는 자기 칸에만 씁니다. 두 에이전트가 같은 칸을 고쳐 서로의 글을 지우는 일을 구조적으로 막습니다.

  • 덧붙이기만 한다 — 회신은 기존 글 아래에 날짜·역할과 함께 쌓입니다. 별도 로그 없이 칸 하나가 이력입니다.

  • 쓰기는 눈에 띄게 — 쓰기 도구는 설명에 [쓰기] 를 달고, 서버 안내문으로 "문구를 먼저 보여 줄 것"을 요구합니다. 공유 문서를 조용히 바꾸지 않습니다.

  • 비밀값은 코드 밖 — 키·시트 ID 는 환경 변수로만 받습니다. 오류 메시지에도 키 경로를 싣지 않습니다. .gitignore 가 *.json·.env 를 막습니다.

  • 시트 모양에 덜 민감하게 — 헤더를 위치가 아니라 No. 로 찾고, 열을 이름으로 찾습니다. 시트가 12.0 으로 돌려주는 번호도 12 로 맞춥니다.

  • 사람이 읽기 좋게 쓴다 — API 로 쓴 긴 글이 옆 칸으로 넘치지 않게 줄바꿈을 켜고, 글자 폭(한글 13px·영문 7px)으로 필요한 행 높이를 계산해 키웁니다. 그림이 든 행을 위해 줄이지는 않습니다.

  • 토큰을 아낀다 — 목록은 칸을 300자에서 자르고, 자세한 내용은 한 건만 get_issue 로 읽습니다.

  • 작게 유지한다 — 파일 하나, 의존성 3개(mcp · gspread · google-auth), 상태 없음. 읽고 고치기 쉬운 크기가 목표입니다.

10. 한계

  • 시트 속 이미지는 읽지 못합니다(Sheets API 제약). 필요하면 …/export?format=xlsx 로 받아서 봅니다.

  • 알림이 없습니다. 상대가 적었는지는 "시트 확인해"라고 해야 읽습니다. 실시간 협업 도구가 아니라 비동기 인계용입니다.

  • 사람이 같은 칸을 편집하는 순간과 겹치면 나중에 쓴 쪽이 남습니다. 쓰기는 칸 하나 단위라 범위는 좁습니다.

  • 열 이름 No. 상태 연결탭 등은 한국어 기준입니다. 내 칸·상대 칸·탭·완료 상태값은 설정으로 바꿀 수 있습니다.

  • 2~5명 규모를 생각하고 만들었습니다. 권한·워크플로가 필요한 팀이라면 정식 이슈 트래커가 맞습니다.

11. 개발

.venv/Scripts/python -m pip install -e ".[dev]"
.venv/Scripts/python -m pytest -q        # 시트 접속 없이 도는 순수 함수 시험
.venv/Scripts/python -m ruff check src tests
src/async_sheet_mcp/server.py   MCP 서버 (도구 7개)
tests/test_helpers.py           헤더 찾기 · 번호 정규화 · 회신 형식 · 행 높이 계산
.env.example                    설정 예시 (실제 값은 커밋하지 않음)

MIT License

Available Tools

7 tools
add_issueA

[쓰기] 표 맨 아래에 새 행(다음 번호, 오늘 날짜). 문제 등록이나 상대에게 묻는 질문에 쓴다. mode 는 '모드'(분류) 칸, problem 은 '문제점' 칸, model 은 '모델' 칸(비우면 역할 이름), note 는 내 칸. 사용자가 맡긴 범위 안에서만 부를 것.

Inputs: mode (required), problem (required), note, model, +1 more. Returns: object

append_commentA

[쓰기] No.{no} 의 내 칸 끝에 "[M/D 역할] text" 를 새 줄로 덧붙인다(기존 내용은 지우지 않는다). date 를 비우면 오늘 M/D. 공유 문서를 바꾸므로 사용자가 맡긴 범위 안에서만 부를 것.

Inputs: no (required), text (required), date. Returns: object

get_issueC

한 건 전체(자르지 않음) + '연결탭'이 있으면 그 탭의 텍스트.

Inputs: no (required). Returns: object

list_issuesA

문제점 목록. status: 'open'(끝난 상태 제외, 기본) / 'all' / 특정 상태값(예: '재등록'). 긴 칸은 text_limit 글자에서 자른다(0 이면 자르지 않음).

Inputs: status, text_limit. Returns: result

list_tabsC

시트의 탭 이름 목록.

Inputs: no named parameters. Returns: result

read_tabB

탭 하나를 텍스트로(빈 행 제외, 칸은 ' | ' 로 연결). 이미지는 포함되지 않는다.

Inputs: name (required), max_rows. Returns: result

set_statusB

[쓰기] No.{no} 의 '상태' 칸을 바꾼다(예: 확인중, 完). 사용자가 맡긴 범위 안에서만 부를 것.

Inputs: no (required), status (required). Returns: object

Tool Schema Changelog

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

Loading tool schema changelog…

    TDQS

    A3.5/5.0

    Scored across 7 tools

    Disambiguation4/5

    Each tool targets a distinct resource+action: tabs (list_tabs/read_tab), issues (list_issues/get_issue), and three distinct write targets (append_comment, set_status, add_issue). The only mild overlap is read_tab, which can also dump the issues tab and thus partially duplicate list_issues, and get_issue returns linked-tab text that read_tab could also fetch; descriptions resolve this but do not eliminate it.

    Naming Consistency4/5

    All seven names use snake_case verb_noun form (list_tabs, get_issue, append_comment, set_status, add_issue), which is highly predictable. Minor deviation: retrieval verbs are mixed (list/get/read), so an agent cannot guess whether a fetch is called get_* or read_* without looking.

    Tool Count5/5

    Seven tools is well inside the ideal 3-15 range and each maps to a real workflow step (navigate tabs, browse/filter issues, inspect one issue, append a comment, change status, register a new issue). Nothing looks redundant or padded.

    Completeness4/5

    The issue lifecycle is largely covered: create (add_issue), read at summary and full detail level, status transition (set_status), and comment append — a sensible surface for a shared sheet tracker. Gaps remain: no way to edit existing 問題點/모드/모델 fields or delete/reopen a row other than via set_status, and no search beyond a status filter, though append_comment partially compensates.

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      Not graded
      quality
      C
      maintenance
      An MCP server that enables AI agents to read, create, and modify Google Spreadsheets through actions like editing cells and managing sheets. It features a specialized handoff protocol to synchronize tasks and state between different LLMs using a shared spreadsheet log.
      599 npm
      MIT
    • A
      license
      Not graded
      quality
      B
      maintenance
      Enables AI tools to seamlessly hand off work by creating, accepting, and completing standardized Markdown handoff documents, so a task can move between different AI assistants without repeating context.
      MIT
    • A
      license
      Not graded
      quality
      B
      maintenance
      Enables AI agents to create, format, and verify Google Sheets with native tables, themes, validation, linting, rendering, and safeguards for human-edited spreadsheets.
      MIT
    • A
      license
      A
      quality
      B
      maintenance
      Self-hosted task tracker and MCP server for AI coding agents. Append-only case files preserve decisions, failed attempts, questions, and check results across sessions. A live web board lets people track progress and answer agents. Runs locally in Docker and connects to Claude Code, Codex, Cursor, and other Streamable HTTP MCP clients. MIT licensed.
      30
      6
      MIT