@itapi-core/mcp-tistory

MCP server for Tistory blog automation — auto login with ID/PW, post write/modify/draft, image upload, categories.

티스토리 공개 API(OAuth)는 카카오가 종료했습니다. 이 서버는 카카오 계정 ID/PW로 자동 로그인 후 내부 관리 API를 사용합니다.

Tools

인증 & 설정 (Auth & Setup)

| Tool | viruagent | Description | |------|-----------|-------------| | tistory_auth_status | /login | 현재 세션 상태 확인 | | tistory_session_logout | /logout | 세션 파일 삭제 및 로그아웃 | | tistory_blog_set_name | - | 블로그 이름(서브도메인) 수동 설정 | | tistory_set_defaults | /set category /set visibility | 기본 카테고리/공개설정 변경 |

블로그 & 포스트 (Blog & Post)

| Tool | viruagent | Description | |------|-----------|-------------| | tistory_blog_get_info | - | 블로그 목록 조회 | | tistory_post_list | /list | 글 목록 조회 | | tistory_post_check_duplicate | - | 제목이 기존 글/임시저장과 겹치는지 사전 확인 | | tistory_post_get | /preview | 특정 글 내용 조회 | | tistory_post_write | /publish | 새 글 작성 및 발행 (마크다운/SEO 체크 지원) | | tistory_post_modify | /edit | 기존 글 수정 (마크다운/SEO 체크 지원) | | tistory_post_draft | /draft | 글 임시저장 (작성 또는 draftSequence로 수정, 마크다운/SEO 체크 지원) | | tistory_post_attach | - | 이미지 업로드 | | tistory_post_delete | - | 글 삭제 |

임시저장 글 (Drafts)

| Tool | Description | |------|-------------| | tistory_draft_list | 임시저장 글 목록 조회 | | tistory_draft_get | 특정 임시저장 글의 상세 내용 조회 | | tistory_draft_delete | 특정 임시저장 글 삭제 |

카테고리 (Category)

| Tool | viruagent | Description | |------|-----------|-------------| | tistory_category_list | /categories | 카테고리 목록 조회 ({ "카테고리명": id }) |

Setup

1. 설치 및 빌드

npm install
npx playwright install chromium   # 자동 로그인에 필요
npm run build

2. MCP Client Configuration

TISTORY_ID와 TISTORY_PW를 설정하면 세션이 없을 때 자동으로 로그인합니다.
세션은 ~/.tistory-mcp/session.json에 저장되어 재사용됩니다.

{
  "mcpServers": {
    "tistory": {
      "command": "npx",
      "args": ["-y", "@itapi-core/mcp-tistory"],
      "env": {
        "TISTORY_ID": "your_kakao_email",
        "TISTORY_PW": "your_kakao_password",
        "TISTORY_BLOG_NAME": "myblog"
      }
    }
  }
}

Environment Variables

| Variable | Required | Description | |----------|----------|-------------| | TISTORY_ID | ✅ | 카카오 계정 이메일 또는 전화번호 | | TISTORY_PW | ✅ | 카카오 계정 비밀번호 | | TISTORY_BLOG_NAME | ❌ | 기본 블로그 서브도메인 (미설정 시 대표 블로그 자동 감지) | | TISTORY_SESSION_FILE | ❌ | 세션 파일 경로 (기본: ~/.tistory-mcp/session.json) | | TISTORY_COOKIES | ❌ | 쿠키 문자열 직접 입력 (ID/PW 대신 사용) | | PORT | ❌ | 컨테이너 내부 HTTP 포트 (기본: 3000) | | HOST | ❌ | HTTP 바인드 주소 (기본: 0.0.0.0, 모든 IP에서 접속 허용) | | HOST_PORT | ❌ | Docker 외부(호스트) 포트 (기본: 13000, 원하는 포트로 변경 가능) | | TRANSPORT | ❌ | stdio | http |

동작 방식

MCP Tool 호출
  └─ 세션 파일 확인 (~/.tistory-mcp/session.json)
       ├─ 있으면 → 쿠키로 API 호출
       │            └─ 응답이 "세션 만료"로 판단되면(401/403 또는 비-JSON 응답)
       │               기존 세션 폐기 → TISTORY_ID/PW로 재로그인 → 세션 저장 → 1회 재시도
       └─ 없으면 → TISTORY_ID/PW로 Playwright headless 자동 로그인
                   → 세션 저장 → API 호출

세션이 중간에 만료되더라도(예: 장시간 미사용, 외부에서 로그아웃 등) 별도의 수동 재로그인 없이 자동으로 재로그인 후 요청을 이어갑니다. 재로그인까지 실패한 경우에만 오류가 반환됩니다.

자동 로그인 브라우저는 실행 환경의 시스템 로케일과 무관하게 항상 ko-KR / Asia/Seoul 기준으로 접속합니다. 해외 리전 서버나 컨테이너에서 실행해도 카카오/티스토리 화면이 영어 등 다른 언어로 나오지 않습니다.

Docker

.env 파일에 계정 정보를 설정한 뒤 실행합니다:

# .env
TISTORY_ID=your_kakao_email
TISTORY_PW=your_kakao_password
TISTORY_BLOG_NAME=myblog   # 선택사항

docker-compose up -d

• 세션은 Docker volume tistory-session에 저장되어 컨테이너 재시작 후에도 유지됩니다.
• 카카오 2단계 인증이 설정된 계정은 첫 실행 시 tistory_auth_status 도구로 세션 상태를 확인하세요.
• HTTP 엔드포인트: http://localhost:${HOST_PORT}/mcp (기본: http://localhost:13000/mcp)
• 외부 접속 및 reverse proxy를 위해 컨테이너는 0.0.0.0:3000에서 수신합니다. Nginx/Cloudflare 등 reverse proxy에서는 /mcp를 이 주소로 전달하면 됩니다.

마크다운 작성 & SEO 체크

tistory_post_write / tistory_post_modify / tistory_post_draft는 다음을 지원합니다.

• contentFormat: 기본값은 "markdown"입니다. content에 GFM 마크다운을 그대로 넘기면 서버에서 HTML로 변환해 저장합니다. (Tistory 자체 "마크다운 모드"도 저장 시 클라이언트에서 HTML로 변환해 보내는 방식이라 결과는 동일합니다. 서버에는 "마크다운으로 썼다"는 상태 자체가 남지 않으므로, 재편집 시 관리 화면은 항상 "기본모드"로 열립니다.) 이미 완성된 HTML을 그대로 저장하려면 contentFormat: "html"을 명시하세요.
• 중복 작성 방지: tistory_post_write/tistory_post_draft는 저장할 때마다 블로그 RSS(최근 최대 50개 글)와 임시저장 전체 제목을 자동으로 비교합니다.
  • 완전히 같은 제목이 있으면 tistory_post_write는 발행을 거부합니다(오류로 중단, 목록 표시). 정말 중복이 아니라면 allowDuplicate: true로 강제 진행할 수 있습니다.
  • 제목이 비슷하기만 하면 막지 않고 응답의 duplicateWarning 필드로 후보 목록만 알려줍니다.
  • tistory_post_check_duplicate 도구로 제목을 정하기 전에 미리 확인할 수도 있습니다.
• 자동 SEO 체크: 세 도구 모두 호출할 때마다 응답에 seo 필드(0~100점 + 항목별 pass/warn)를 함께 반환합니다. 검사 항목:
  • 제목 15~40자
  • 본문 1000자 이상, h2/h3로 구조화 (본문에 h1 금지 — 글 제목이 이미 h1)
  • 태그 5~10개
  • 첫 문단(도입부) 60~160자 — 검색결과 설명으로 노출됨
  • 이미지 alt 텍스트
  • 참고/출처 링크 1개 이상
  • (선택) focusKeyword 지정 시 제목/도입부/소제목에 일관되게 등장하는지
• MCP 서버 instructions에도 위 체크리스트가 포함되어 있어, 이 MCP를 사용하는 모델은 별도 요청 없이도 매번 SEO를 고려해 글을 작성하도록 유도됩니다.
• 권장 흐름: tistory_post_draft로 초안을 저장 → 응답의 seo.checks에서 warn 항목 보완 → tistory_post_write(신규) 또는 tistory_post_modify(수정)로 발행.

Visibility 값

| 값 | 설명 | |----|------| | 0 | 비공개 | | 15 | 보호 (비밀번호) | | 20 | 공개 (기본값) |