Tistory MCP (Unofficial)

tistory-mcp

티스토리(Tistory) 블로그를 위한 AI 글쓰기 보조 MCP 서버 — Claude Code·Cursor 같은 MCP 클라이언트에서 내 블로그 글을 읽고, 쓰고, 다듬습니다. 공개 여부는 사람이 결정합니다.

An unofficial MCP server for Tistory blogs — an AI writing assistant where a human reviews before anything goes public.

English README

비공식 · 카카오/티스토리와 무관. 티스토리 Open API 는 2024년 2월에 종료되었습니다. 이 프로젝트는 브라우저에서 카카오 로그인을 한 번 마친 뒤 내 PC 에 저장한 쿠키로, 티스토리 관리자 화면이 쓰는 내부 JSON API 를 호출합니다. 카카오·티스토리와 아무 관계가 없고, 티스토리 내부가 바뀌면 언제든 멈출 수 있습니다. 엔드포인트 지식은 MIT 라이선스로 공개된 kim-se-hee/tistory-mcp 의 실측 문서를 따릅니다 — 그 프로젝트는 npm 에 tistory-mcp 로 배포되는 별개의 TypeScript 프로젝트입니다. npx tistory-mcp 와 uvx tistory-mcp 는 서로 다른 프로젝트이며, 이 저장소는 Python/PyPI 쪽입니다.

왜 tistory-mcp 인가

• 글쓰기는 AI, 공개는 사람. 발행 기본값이 비공개입니다. AI 가 쓴 글을 티스토리에서 직접 읽어 본 뒤 공개로 바꾸는 흐름이 기본이고, 공개 발행은 사용자가 명시적으로 요청해야 합니다.
• 내 PC 를 벗어나지 않습니다. 로그인 쿠키는 로컬 0600 파일(또는 OS keyring)에만 저장되고, 티스토리 외 어디에도 전송되지 않습니다. 텔레메트리 없음.
• 클라이언트를 가리지 않습니다. 표준 stdio MCP 서버라 Claude Code, Claude Desktop, Cursor, VS Code, Codex CLI, Gemini CLI 등 어디서나 같은 11개 도구를 씁니다.

기능

• 마크다운 → 티스토리 에디터 서식(data-ke-* 속성)이 붙은 HTML 변환. 제목·표·인용·목록·이미지가 에디터로 쓴 글처럼 보입니다(코드 블록은 일반 <pre><code> 로 나갑니다).
• 새 글 발행(비공개 기본) · 본문 수정 · 삭제 · 카테고리 조회 · 비공개 글을 포함한 목록과 본문 조회.
• 이미지 업로드 — 본문에 넣을 치환자와 첨부 참조를 함께 돌려줘 이미지가 나중에 깨지지 않게 합니다.
• 에디터 자동저장 슬롯에 초안 저장("이어서 작성"으로 복원).
• 로그인 없이 아무 티스토리 블로그의 공개 글 RSS 조회.
• 터미널 CLI(login / status / logout) — MCP 클라이언트의 도구 타임아웃을 피해 터미널에서 로그인.

안전 기본값

빠른 시작 (3단계)

1. 설치

uv 가 있으면 uvx 가 패키지를 받아 실행합니다.

# macOS / Linux
curl -LsSf https://astral.sh/uv/install.sh | sh

# Windows (PowerShell)
powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"

로그인 창을 띄울 브라우저가 필요합니다. Chrome 또는 Edge 가 설치돼 있으면 이 단계는 건너뛰어도 됩니다 (로그인은 번들 Chromium → Chrome → Edge 순으로 시도).

uvx tistory-mcp install-browser   # Playwright Chromium 다운로드, 최초 1회 약 300MB

pipx install tistory-mcp          # 또는 가상환경에서 pip install tistory-mcp
tistory-mcp --version

git clone https://github.com/jangsejong/tistory-mcp.git
cd tistory-mcp
bash scripts/setup.sh             # venv + 의존성 + Chromium + ruff/pytest  (--no-browser 로 Chromium 생략)
claude mcp add tistory -- "$PWD/.venv/bin/tistory-mcp"

python scripts/mcp_probe.py .venv/bin/tistory-mcp                    # initialize + tools/list 핸드셰이크
python scripts/mcp_call.py  .venv/bin/tistory-mcp -- tistory_fetch_public_posts '{"blog_url":"example.tistory.com","limit":3}'
python scripts/mcp_call.py  .venv/bin/tistory-mcp -- tistory_publish_post @args.json   # 긴 본문은 @파일

2. 클라이언트에 등록

Claude Code 예시(다른 클라이언트는 아래):

claude mcp add tistory --scope user -- uvx tistory-mcp

3. 블로그 연결

새 세션을 열고 AI 에게 말합니다.

내 티스토리 블로그 myblog.tistory.com 연결해줘

브라우저 창이 뜨면 카카오 로그인 → 카카오톡 푸시 승인을 직접 마칩니다. 쿠키가 저장되면 끝입니다. 이후에는 세션이 만료될 때까지 브라우저 없이 동작합니다. 세션 수명은 일정하지 않습니다 — 실측(2026-10-27)에서 어떤 세션은 로그인 뒤 한 시간 남짓 만에 만료됐고, 다른 세션은 90분 동안 호출이 없어도 다섯 시간 가까이 유지됐다가 여섯 시간 쉬는 사이에 만료됐습니다. 만료되면 도구가 알려 주므로 다시 로그인하면 됩니다.

바로 써 볼 만한 요청:

./post.md 를 '개발' 카테고리에 비공개로 올려줘. 태그는 python, mcp.

클라이언트별 설정

대부분의 클라이언트는 아래 한 줄이면 됩니다. 환경변수는 각 클라이언트의 env 항목으로 넘깁니다.

{"mcpServers":{"tistory":{"command":"uvx","args":["tistory-mcp"]}}}

claude mcp add tistory --scope user -- uvx tistory-mcp
claude mcp list        # 확인
claude mcp remove tistory

/plugin marketplace add jangsejong/tistory-mcp
/plugin install tistory@tistory-mcp
``` 로그인 도구가 도중에 끊기면 서버 항목에 `"timeout"`(밀리초)을 주거나 `MCP_TOOL_TIMEOUT` 환경변수를 늘리고, 그래도 안 되면 터미널에서 `tistory-mcp login` 을 쓰세요.

</details>

<details>
<summary>Claude Desktop</summary>

설정 파일(Claude 메뉴 → Settings → Developer → Edit Config):

- macOS: `~/Library/Application Support/Claude/claude_desktop_config.json`
- Windows: `%APPDATA%\Claude\claude_desktop_config.json`

```json
{
  "mcpServers": {
    "tistory": {
      "command": "uvx",
      "args": ["tistory-mcp"]
    }
  }
}

{
  "mcpServers": {
    "tistory": {
      "command": "uvx",
      "args": ["tistory-mcp"]
    }
  }
}

{
  "servers": {
    "tistory": {
      "type": "stdio",
      "command": "uvx",
      "args": ["tistory-mcp"]
    }
  }
}

codex mcp add tistory -- uvx tistory-mcp

[mcp_servers.tistory]
command = "uvx"
args = ["tistory-mcp"]

gemini mcp add -s user tistory uvx tistory-mcp

{
  "mcpServers": {
    "tistory": {
      "command": "uvx",
      "args": ["tistory-mcp"]
    }
  }
}

그 밖의 클라이언트는 위의 공통 JSON(mcpServers 형식)을 해당 클라이언트의 MCP 설정 파일에 넣으면 됩니다.

첫 로그인

tistory_session_init 도구(또는 AI 에게 "블로그 연결해줘")가 브라우저 창을 띄웁니다. 카카오 로그인과 카카오톡 푸시 승인은 사용자가 직접 합니다 — 이 2단계 인증은 자동화할 수 없고, 그래서 완전 무인 운영은 설계상 불가능합니다. 로그인이 끝나면 쿠키만 저장되고 창은 닫힙니다.

창이 안 뜨거나 클라이언트가 기다려 주지 않을 때의 대안 세 가지:

1) 터미널에서 로그인(권장) — MCP 클라이언트의 도구 타임아웃과 무관하게 최대 5분(--timeout)을 기다립니다.

tistory-mcp login myblog.tistory.com          # uvx 사용 시: uvx tistory-mcp login myblog.tistory.com
tistory-mcp status myblog.tistory.com         # 저장된 세션과 유효 여부
tistory-mcp logout myblog.tistory.com         # 세션 삭제

2) 이미 떠 있는 브라우저에 붙기 (WSL · SSH · 컨테이너 등 화면이 없는 환경) — 화면이 있는 쪽(예: Windows 데스크톱)에서 원격 디버깅 포트를 열고 브라우저를 띄운 뒤, 서버에는 그 주소만 알려 줍니다.

:: Windows 데스크톱 — Edge 또는 Chrome
msedge --remote-debugging-port=9222 --user-data-dir=%TEMP%\tistory-login
chrome --remote-debugging-port=9222 --user-data-dir=%TEMP%\tistory-login

# WSL 등 서버 쪽
tistory-mcp login myblog.tistory.com --cdp-url http://127.0.0.1:9222
# 도구로 할 때는 cdp_url="http://127.0.0.1:9222", 또는 환경변수 TISTORY_MCP_CDP_URL

붙은 브라우저의 쿠키를 읽어 오므로, 평소 쓰는 프로필 대신 전용 --user-data-dir 를 쓰는 것을 권합니다. CDP 주소는 기본적으로 loopback 만 허용됩니다.

3) 원격 서버 — 로컬 PC 에서 2) 처럼 브라우저를 띄운 뒤, 로컬 PC 에서 서버로 접속하면서 서버 쪽 포트를 내 브라우저로 역방향 포워딩합니다. 서버에서는 여전히 127.0.0.1:9222 로 보이므로 원격 허용 설정이 필요 없습니다.

ssh -R 9222:127.0.0.1:9222 user@server     # 로컬 PC 에서 실행 — 서버의 127.0.0.1:9222 → 내 브라우저

도구

도구 설명은 영문과 한국어를 병기해 어느 언어로 대화해도 같은 안내를 받습니다.

이런 식으로 써보세요

myblog.tistory.com 카테고리 보여줘

./post.md 를 '개발' 카테고리에 비공개로 올려줘. 태그는 python, mcp

./diagram.png 올려서 두 번째 문단 뒤에 넣고, 비공개로 발행해줘

검토했어. 방금 올린 글 공개로 바꿔줘

제목에 '회고' 들어간 글 찾아서 오타만 고쳐줘. 공개 상태는 그대로

example.tistory.com 최근 글 5개 요약해줘        (남의 블로그 공개 글 — 로그인 불필요)

이 내용은 초안으로만 저장해 둬. 발행은 하지 말고

내 블로그 세션 아직 살아 있어?

발행 워크플로

AI 가 쓰고 사람이 검토한 뒤 공개하는 기본 흐름입니다.

1. tistory_get_categories — 카테고리 id 를 얻습니다(이름은 받지 않음).
2. tistory_upload_image — 이미지마다 호출해 substitution 은 본문에, attachment_ref 는 attachments 목록에 넣습니다.
3. tistory_publish_post — 마크다운 본문으로 비공개 발행. 응답의 글 번호를 기억합니다.
4. 티스토리 관리자 화면에서 글을 읽어 봅니다. 고칠 게 있으면 AI 에게 말해 tistory_update_post 로 본문을 다시 보냅니다(마크다운이면 content_format="markdown").
5. 마음에 들면 tistory_update_post 에 visibility="public" — 이때 비로소 공개됩니다.

발행이 오류나 타임아웃으로 끝났다면 바로 다시 호출하지 말고 tistory_list_posts 로 글이 생겼는지 먼저 확인하세요. 서버는 호출마다 새 글을 만듭니다.

환경변수

클라이언트 설정의 env 로 넘긴 값은 클라이언트를 다시 시작해야 반영됩니다.

세션 파일 위치 (file 저장소, 권한 0600):

같은 디렉터리의 ratelimit.json 이 속도 제한 상태입니다.

검증 현황

11개 도구 모두 실제 블로그에서 확인했습니다(2026-10-27, 비공개 테스트 글로 검증 뒤 삭제). 티스토리 쪽 변경으로 동작이 달라지면 이슈로 알려 주세요(쿠키·세션 파일은 첨부하지 마세요).

문제 해결 / FAQ

더 자세한 내용은 docs/TROUBLESHOOTING.md.

• "세션이 만료되었습니다" — 로그인 세션 쿠키(TSSESSION)는 만료일이 없는 세션 쿠키라 서버 쪽에서 끊깁니다. 실측에서는 한 시간 남짓 만에 만료된 세션도, 다섯 시간 가까이 유지되다 여섯 시간 쉬는 사이에 만료된 세션도 있어 수명을 예측할 수 없습니다. 하룻밤 지나면 다시 로그인한다고 보면 됩니다. tistory_session_init 을 다시 실행하거나 터미널에서 tistory-mcp login myblog.tistory.com.
• Executable doesn't exist / 브라우저를 찾지 못함 — tistory-mcp install-browser 로 Chromium 을 받거나 Chrome/Edge 를 설치하세요. 로그인은 번들 Chromium → Chrome → Edge 순으로 시도합니다.
• 로그인 창이 안 보임 (WSL · SSH · 컨테이너) — 화면이 있는 쪽에서 --remote-debugging-port=9222 로 브라우저를 띄우고 cdp_url 로 붙으세요. 첫 로그인 참고.
• 로그인 중 클라이언트가 타임아웃 — 터미널에서 tistory-mcp login myblog.tistory.com 으로 먼저 로그인해 두면 도구는 저장된 쿠키만 씁니다. Codex CLI 는 tool_timeout_sec, Claude Code 는 서버 항목의 timeout 으로 제한을 늘릴 수도 있습니다.
• 커스텀 도메인 블로그 — blog_url 은 원래 주소 myblog.tistory.com 을 권장합니다. 커스텀 도메인을 그대로 써야 하면 TISTORY_MCP_ALLOW_ANY_HOST=1.
• "간격 제한" / "일일 상한" 오류 — 기본 60초·20회/일 입니다. TISTORY_MCP_MIN_INTERVAL_SEC, TISTORY_MCP_DAILY_CAP 으로 조정(0 = 해제). 상한은 발행·수정 합산이며 TISTORY_MCP_HOME/ratelimit.json 에 기록됩니다.
• 이미지가 15일쯤 뒤에 깨짐 — 발행·수정 때 attachments 에 attachment_ref 를 넣지 않은 경우입니다. 해당 글을 tistory_update_post 로 다시 보내면서 attachments 를 채우세요(이미지는 다시 업로드).
• 태그 표기가 바뀜 — 이미 쓰던 태그와 대소문자·띄어쓰기만 다른 태그는 기존 표기로 합쳐지는 것으로 보입니다. 티스토리 쪽 동작입니다.
• 두 대의 PC 에서 같은 블로그에 로그인 — 동시 로그인 시 한쪽 세션이 끊기는지 확인되지 않았습니다. 한 PC 에서 쓰는 것을 권합니다.
• update_post 에 마크다운을 보냈더니 기호가 그대로 보임 — update_post 의 content_format 기본값은 html 입니다. 마크다운이면 content_format="markdown" 을 명시하세요(publish_post 는 기본 markdown).
• get_post 본문이 마크다운이 아님 — 티스토리는 마크다운을 저장하지 않습니다. 돌아오는 것은 스킨으로 렌더된 HTML 이며, 수정할 때는 그 HTML 을 되돌려 보내지 말고 새 본문을 써서 보내세요.

한계와 면책

• 비공식입니다. 티스토리가 내부 API 를 바꾸면 예고 없이 동작이 멈출 수 있습니다.
• 이 도구의 사용은 티스토리·카카오 약관과 충돌할 수 있습니다. 계정 제한 등 모든 위험은 사용자 본인이 집니다.
• 완전 무인 운영은 불가능합니다(카카오톡 푸시 승인). 세션은 짧으면 한 시간 남짓 만에 만료되므로(실측), 도구가 만료를 알리면 다시 로그인해야 합니다.
• 속도 제한은 프로세스 안에서만 직렬화됩니다. 두 클라이언트가 동시에 발행하면 간격 검사가 겹칠 수 있습니다.
• 텔레메트리·외부 서버 없음. 쿠키는 티스토리로 보내는 요청 외에는 이 PC 를 떠나지 않습니다.

허용하지 않는 사용

• 대량·반복 발행, 같은 글을 여러 블로그에 뿌리기, 스팸.
• 검색엔진 조작을 노린 글 양산.
• 본인 소유가 아닌 블로그·계정에 글 쓰기.
• 티스토리·카카오 약관이 금지하는 행위 전반.

이 프로젝트는 내 블로그를 위한 글쓰기 보조이며, 공개 전에 사람이 읽는 것을 전제로 만들었습니다.

보안

• 저장된 쿠키는 블로그 관리자 권한 그 자체입니다. 세션 파일을 복사·공유하지 마세요.
• 이슈·PR 에 쿠키, 세션 JSON, HAR, 스크린샷 속 토큰을 절대 첨부하지 마세요.
• 텔레메트리 없음. 네트워크 요청은 로그인한 티스토리 호스트와 RSS 조회 대상 블로그로만 나갑니다.
• 취약점 신고 절차는 SECURITY.md.

기여

버그 신고와 PR 을 환영합니다 — CONTRIBUTING.md. 내부 구조는 docs/ARCHITECTURE.md. 테스트는 네트워크 없이 돕니다(pytest, 모의 HTTP).

라이선스

MIT

감사

• kim-se-hee/tistory-mcp (MIT) — 티스토리 내부 엔드포인트를 실측해 정리한 docs/api.md. 이 저장소의 엔드포인트 지식은 그 문서를 따릅니다. npm 에 배포되는 별개의 TypeScript 프로젝트입니다.
• aiarchitecturedev/aiarchitect-blog-mcp — 도구 annotation 과 fail-closed 패턴을 참고했습니다.

Changelog

v0.2.0 (2026-10-27)

• 문서: 세션 수명 서술 정정 — "며칠~몇 주"가 아니라 실측 한 시간 남짓 만에 만료될 수 있음(TSSESSION 은 만료일 없는 세션 쿠키)
• 문서: 마크다운 변환 설명 정정 — 에디터 서식 속성은 제목·표·인용·목록에만 붙고 코드 블록은 일반 <pre><code>
• 문서: 세션 수명 서술 보강 — 한 시간 남짓 만에 만료된 세션도, 90분 무호출을 포함해 다섯 시간 가까이 유지되다 여섯 시간 무호출 사이에 만료된 세션도 있었음(실측 2026-10-27~28, 수명 예측 불가)
• 저장소: .gitignore 에 /_private/(로컬 전용 내부 자료 폴더) 추가

첫 공개 릴리스.

• 도구 11개 — 세션(init/status), 카테고리, 글 목록·조회, 공개 RSS, 발행·수정·삭제, 이미지 업로드, 자동저장 초안. 도구 설명·title 영문+한국어 병기.
• 안전 기본값 — 비공개 발행, 삭제 confirm + destructiveHint, 발행·수정 속도 제한(60초·하루 20회, 스레드 락), *.tistory.com 한정, CDP loopback 한정, nh3 본문 정화.
• 이미지 치환자 엄격 검증 — 비공개 0.1.x 에서 발견된 sanitize 우회를 수정.
• 발행 실패 뒤 재시도 시 중복 글 경고.
• 로그인 — 번들 Chromium → Chrome → Edge 순 폴백, cdp_url 로 외부 브라우저 접속, keyring 오류 안내.
• 배포 — PyPI tistory-mcp(uvx tistory-mcp), CLI 서브커맨드 install-browser / login / status / logout / --version.
• tistory_list_posts — 공개 범위 필터를 서버 어휘(visible/hidden/protect)로 매핑(다른 값은 서버가 400). search_type 에 tag 추가, 서버가 거부하는 all 제거.
• 실계정 검증 — 11개 도구 전부 실제 블로그에서 확인(비공개 테스트 글로 검증 뒤 삭제).
• Python ≥3.11.
• 비공개 개발 단계(v0.1.0v0.1.4, 2026-0910)의 이력은 이 항목으로 요약.