TimelinesAI MCP Server

팀을 위한 WhatsApp 인박스인 TimelinesAI 공개 API를 Claude에 노출하는 MCP(Model Context Protocol) 서버입니다. Railway에 읽기 전용 모드로 배포하도록 설계되었습니다.

👉 배포 단계는 DEPLOY-RAILWAY.md에 있습니다.

하는 일

Claude에게 인박스를 읽고 운영할 수 있는 12가지 도구를 제공합니다: 채팅, 메시지, 라벨, 담당자, 연결된 번호, 팀 — 여기에 범용 도구 하나, 탐색 도구 하나, 인박스 집계 요약까지 포함됩니다.

환경 변수

세 가지 제한(reja)

이 MCP는 실제 사람과 대화합니다. WhatsApp으로 보낸 메시지는 몇 초 안에 상대방의 휴대폰에 도착하며 되돌릴 수 없습니다. 그래서 서로 독립적인 잠금장치가 세 개 있습니다.

1. TIMELINES_READ_ONLY — 기본값은 전송 방식에 따라 다름

• stdio(로컬): 쓰기 허용이 기본값.

• http(원격): 쓰기 차단이 기본값.

공개 배포에서 이 변수를 잊으면 자동으로 읽기 전용이 됩니다.

2. TIMELINES_ALLOW_SEND — 전송 제한

두 전송 방식 모두에서 기본적으로 꺼져 있으며, 로컬에서도 마찬가지입니다. 쓰기를 활성화해도 TIMELINES_ALLOW_SEND=1을 설정하기 전까지는 메시지 전송이 계속 차단됩니다.

이유는 비대칭성 때문입니다: 라벨 변경, 채팅 재배정, 채팅 닫기는 내부적이고 되돌릴 수 있는 작업입니다. 고객에게 WhatsApp을 보내는 것은 그렇지 않습니다. 둘이 같은 스위치를 공유하는 것은 말이 안 됩니다.

3. confirm=true — 호출별 제한

모든 전송은 위 조건 외에도 confirm=true를 요구합니다. 파일 삭제, 웹훅 재구성, 동료 접근 권한 회수와 마찬가지입니다. 도구의 지침은 명시적입니다: 먼저 사용자에게 정확한 수신자와 정확한 텍스트를 보여주고, 사용자의 명시적 승인을 받은 경우에만 확인합니다.

각 거부 메시지는 세 가지 제한 중 어느 것이 막았는지 알려줍니다.

엔드포인트 인증

MCP 프로토콜에는 자체 인증이 없습니다. http 모드에서 이 서버는 모든 요청에 Authorization: Bearer <MCP_AUTH_TOKEN>을 요구하거나, Claude 커넥터용으로 경로에 내장된 비밀값(/s/<secreto>/mcp)을 요구합니다. /healthz만 유일한 공개 경로입니다.

서버는 MCP_AUTH_TOKEN이 없거나 32자 미만이면 시작을 거부합니다.

로컬에서 실행

pip install -r requirements.txt

# stdio (para Claude Desktop)
TIMELINES_API_TOKEN=tla_xxx python timelines_mcp.py

# http (como en Railway)
TIMELINES_MCP_TRANSPORT=http \
TIMELINES_API_TOKEN=tla_xxx \
MCP_AUTH_TOKEN=$(python3 -c "import secrets;print(secrets.token_urlsafe(48))") \
PORT=8000 python timelines_mcp.py

시작 시 어떤 모드로 실행되었는지 출력합니다:

[timelines-mcp] streamable-http on 0.0.0.0:8000  token=set  read_only=True  allow_send=False  sending_enabled=False

TimelinesAI API 참고 사항

공개 레퍼런스(https://timelines.ai/docs/public-api-reference/overview)로 검증됨:

• 기본 URL: https://app.timelines.ai/integrations/api, 인증은 Authorization: Bearer <tla_...>.

• 본문은 JSON으로 전송되며, form-encoded가 아닙니다.

• 응답은 래핑되어 옵니다: {"status":"ok","data":{...}}. 그리고 HTTP 200이지만 status:"error"인 실패도 있습니다 — 이 서버는 이를 성공이 아닌 오류로 처리합니다. 그렇지 않으면 실패한 전송이 전송된 것으로 읽히기 때문입니다.

• 오류에는 필드별 세부 정보가 포함됩니다: {"status":"error","message":..., "error_code":...,"errors":[{"fields":["phone"],"msg":"..."}]}. 오류 메시지에 그대로 표시됩니다.

• 다중 값 필터는 단일 파라미터에서 쉼표로 구분됩니다(label=vip,enterprise). 반복하거나 대괄호를 사용하지 않습니다. Python 리스트를 전달하면 이 형식이 생성됩니다.

• 페이지 크기는 50으로 고정되어 있으며 변경할 수 없습니다. 2026-08-25에 실제 API로 검증됨: limit, per_page, page_size, size, count, take, rows는 모두 무시되며, 각 페이지는 50개 레코드로 도착합니다. 실제로 동작하는 유일한 파라미터는 page이며, 응답의 has_more_pages가 다음 페이지 존재 여부를 알려줍니다. 그래서 도구들은 per_page를 노출하지 않습니다: 조정하는 것처럼 보이지만 아무것도 조정하지 않는 파라미터가 되기 때문입니다.

• 응답 크기를 줄이려면 페이지를 줄이는 방법은 없습니다: 더 필터링하거나, fields를 사용해 필요한 키만 남겨야 합니다. 메시지가 가장 필요한 경우입니다 — 메시지 50개가 있는 채팅은 문자 수 제한을 무난히 초과합니다. fields=["uid","text","from_me","timestamp"]는 대화의 핵심만 크기의 일부로 남깁니다.

• 중복된 필드 이름에 주의: 메시지 레코드에는 래퍼의 data 외에도 자체 data 키(메타데이터 dict)가 있습니다. 그래서 fields는 키 이름이 아닌 위치(리스트 안에 있는 것은 레코드)를 기준으로 무엇을 잘라낼지 결정합니다.

• 전화번호는 국제 형식에 +를 사용합니다: +5215512345678. 모델이 네트워크로 나가기 전에 검증하고 공백과 하이픈을 정리합니다.

• text는 2000자로 제한됩니다; 라벨은 64자, 채팅 이름은 256자.

• whatsapp_account_phone을 생략하면, TimelinesAI는 가장 최근에 연결된 계정에서 전송합니다 — 사용자가 생각하는 계정인 경우는 드뭅니다. 연결된 번호가 여러 개라면 명시적으로 지정하는 것이 좋습니다.

• 전송은 WhatsApp 정책에 따라 메시지 간 ~2초 간격이 있으며, 각 메시지는 크레딧을 소모합니다(텍스트 1개, 첨부 포함 2개; 실패한 것은 환불됩니다).

• 세 가지 서로 다른 한도가 있으며 혼동하지 않는 것이 좋습니다:

  한도	값	적용 대상
  요청 속도	워크스페이스당 분당 50회	전체, 읽기 포함
  월간 볼륨	월 200,000회 호출	전체
  메시징 할당량	요금제에 따름(크레딧)	전송에만 해당

  첫 번째가 문제가 되는 경우입니다: 초과하면 작업 중간에 429 rate_limit_exceeded가 반환되며, 시작 시점이 아닙니다.

  서버는 두 단계로 방어하며, 모든 도구가 적용되도록(페이지네이션 도구뿐만 아니라) 둘 다 요청 계층에 있습니다:

  1. 공유 리듬. 호출 간격은 1.2초입니다(60÷50). 단일 호출은 대기하지 않습니다; 지연은 버스트에서만 나타나며, 이것이 바로 한도에 걸리는 경우입니다. 한도는 워크스페이스 단위이고 모든 도구가 하나를 공유하므로 페이서도 단일합니다.

  2. Retry-After를 사용한 재시도. 읽기에서 429가 발생하면 서버가 요청한 시간만큼 정확히 기다린 후 한 번 재시도합니다. 전송은 절대 자동 재시도하지 않습니다: 아마도 나갔을 메시지를 추측으로 반복하지 않습니다.

  timelines_activity_summary는 또한 중단된 경우 stopped_early 메모와 함께 지금까지 집계한 내용을 반환합니다. 개인별 질문은 페이지를 스캔하는 대신 필터링(responsible=alguien@...)하는 것이 좋습니다: 20번 대신 1번의 요청입니다. 더 큰 한도를 요청하려면 hello@timelines.ai로 문의할 수 있습니다.

• 집계 엔드포인트가 없습니다. 그래서 timelines_activity_summary가 MCP 서버 측에서 페이지를 순회하며 집계하고, 집계가 끝까지 도달하지 못했을 때 complete=false로 알립니다.

보안

• 비밀값은 환경 변수에만 있으며, 코드에 절대 넣지 않습니다. .gitignore가 .env 파일을 차단합니다.

• TimelinesAI 토큰 하나는 워크스페이스 전체에 대한 접근 권한을 부여합니다: 팀의 모든 WhatsApp 대화와 그 전화번호 및 내용을 포함합니다. 실제 고객 정보이므로 그렇게 취급하십시오.

• 공유 토큰 하나는 개인별 추적 가능성이 전혀 없음을 의미합니다.

• 접근을 즉시 차단하려면: TimelinesAI 대시보드에서 토큰을 해지하십시오 — 서버는 즉시 무용지물이 됩니다.