Tistory MCP (Unofficial)

tistory-mcp

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

티스토리 블로그를 위한 비공식 MCP 서버 — 공개前に人が確認するAIライティングアシスタントです。

英語版 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 のキーチェーン）にのみ保存され、ティストーリー以外には送信されません。テレメトリーはありません。
• クライアントを選びません。 標準の stdio MCP サーバーなので、Claude Code、Claude Desktop、Cursor、VS Code、Codex CLI、Gemini CLI など、どこでも同じ11個のツールを利用できます。

機能

• Markdown をティストーリーエディターの書式（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 に伝えます。

私の Tistory ブログ myblog.tistory.com に接続してください

ブラウザーウィンドウが開いたら、カカオログイン → KakaoTalk のプッシュ通知で承認を自分で完了します。Cookie が保存されたら完了です。それ以降は、セッションが期限切れになるまでブラウザーなしで動作します。セッションの有効期間は一定ではありません。実測（2026-10-27）では、ログインから1時間ほどで期限切れになったセッションもあれば、呼び出しがなくても90分から5時間近く維持された後、6時間のあいだに期限切れになったセッションもありました。期限切れになるとツールから通知されるので、再度ログインしてください。

すぐに試せるリクエスト：

./post.md を「開発」カテゴリに非公開で投稿してください。タグは python、mcp です。

クライアントごとの設定

ほとんどのクライアントでは、以下の1行で設定できます。環境変数は各クライアントの 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 に「ブログに接続して」と伝える）を使うと、ブラウザーウィンドウが開きます。カカオログインと KakaoTalk のプッシュ通知での承認は、ユーザー自身で行います。この2段階認証は自動化できないため、完全な無人運用は設計上できません。ログインが完了すると Cookie だけが保存され、ウィンドウは閉じます。

ウィンドウが開かない場合や、クライアントが待機を続けられない場合の代替手段は3つあります。

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

接続したブラウザーの Cookie を読み取るため、普段使っているプロファイルではなく、専用の --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)의 이력은 이 항목으로 요약.