Tistory MCP (Unofficial)

tistory-mcp

面向 Tistory 博客的 AI 写作辅助 MCP 服务 — 在 Claude Code、Cursor 等 MCP 客户端中读取、撰写和润色自己的博客文章。是否公开由人来决定。

面向 Tistory 博客的非官方 MCP 服务 — AI 写作助手，任何内容公开前都由人审核。

English README

非官方 · 与 Kakao/Tistory 无关。 Tistory Open API 已于 2024 年 2 月停止服务。本项目会在浏览器中完成一次 Kakao 登录，然后使用保存在本机的 Cookie 调用 Tistory 管理页面使用的内部 JSON API。本项目与 Kakao/Tistory 毫无关系，Tistory 内部发生变化时随时可能无法运行。端点知识遵循以 MIT 许可证公开的 kim-se-hee/tistory-mcp 的实测文档 — 该项目是通过 npm 发布为 tistory-mcp 的独立 TypeScript 项目。npx tistory-mcp 和 uvx tistory-mcp 属于不同项目，本仓库对应 Python/PyPI 版本。

为什么选择 tistory-mcp

• AI 写作，人来决定是否公开。 发布的默认可见性为非公开。默认流程是先在 Tistory 中直接查看 AI 撰写的文章，再将其改为公开；公开发布必须由用户明确提出请求。
• 不会离开本机。 登录 Cookie 仅保存在本地 0600 文件（或 OS keyring）中，不会发送到 Tistory 以外的任何地方。无遥测。
• 不挑客户端。 这是标准 stdio MCP 服务，因此在 Claude Code、Claude Desktop、Cursor、VS Code、Codex CLI、Gemini CLI 等客户端中都能使用相同的 11 个工具。

功能

• 将 Markdown 转换为带有 Tistory 编辑器格式（data-ke-* 属性）的 HTML。标题、表格、引用、列表和图片看起来就像是在编辑器中编写的一样（代码块会以普通 <pre><code> 输出）。
• 发布新文章（默认非公开）· 修改正文 · 删除 · 查询分类 · 查询文章列表和正文（包括非公开文章）。
• 上传图片 — 同时返回用于插入正文的占位符和附件引用，避免图片之后失效。
• 将草稿保存到编辑器自动保存槽位（可通过“继续撰写”恢复）。
• 无需登录即可查询任意 Tistory 博客的公开文章 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

浏览器窗口弹出后，请自行完成 Kakao 登录 → 批准 KakaoTalk 推送通知。Cookie 保存后即可完成。之后，在会话过期之前都无需打开浏览器即可运行。会话有效期不固定——实测（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 说“帮我连接博客”）会打开浏览器窗口。Kakao 登录和 KakaoTalk 推送批准必须由用户亲自完成——这两步验证无法自动化，因此从设计上就无法完全无人值守。登录完成后，只会保存 Cookie，然后关闭窗口。

如果窗口未弹出，或客户端没有等待足够长的时间，可以使用以下三种替代方法：

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）远程服务——像第 2 种方法一样，在本地电脑上启动浏览器，然后从本地电脑连接到服务，并将服务端口反向转发到浏览器。本地电脑上仍会显示为 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)의 이력은 이 항목으로 요약.