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 변환. 제목·표·인용·목록·이미지가 에디터로 쓴 글처럼 보입니다(코드 블록은 일반 로 나갑니다).
• 새 글 발행(비공개 기본) · 본문 수정 · 삭제 · 카테고리 조회 · 비공개 글을 포함한 목록과 본문 조회.
• 이미지 업로드 — 본문에 넣을 치환자와 첨부 참조를 함께 돌려줘 이미지가 나중에 깨지지 않게 합니다.
• 에디터 자동저장 슬롯에 초안 저장("이어서 작성"으로 복원).
• 로그인 없이 아무 티스토리 블로그의 공개 글 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 / pip 로 설치

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

tistory-mcp --version

이 경우 클라이언트 설정의 command 는 uvx 대신 tistory-mcp 로, args 는 빈 배열로 둡니다.

소스에서 (개발용)

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 Code

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

claude mcp list # 확인 claude mcp remove tistory

--scope user 는 모든 프로젝트에서, 생략(local)하면 현재 프로젝트에서만 보입니다. 프로젝트에 .mcp.json 을 두는 project 범위도 있습니다(이 저장소의 .mcp.json.example 참고).

플러그인으로 설치할 수도 있습니다(같은 uvx tistory-mcp 를 등록):

/plugin marketplace add jangsejong/tistory-mcp

/plugin install tistory@tistory-mcp

Claude Desktop

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

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

{

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

저장 후 Claude Desktop 을 완전히 종료했다가 다시 엽니다. macOS 의 GUI 앱은 셸의 PATH(~/.local/bin 등)를 못 볼 수 있으니 서버가 뜨지 않으면 command 에 which uvx 결과(절대경로)를 넣으세요.

Cursor

전역 ~/.cursor/mcp.json 또는 프로젝트 .cursor/mcp.json:

{

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

위의 "Install in Cursor" 버튼을 눌러도 같은 설정이 들어갑니다.

VS Code (Copilot)

워크스페이스 .vscode/mcp.json (VS Code 는 mcpServers 가 아니라 servers 키를 씁니다):

{

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

사용자 프로필에 두려면 명령 팔레트에서 MCP: Open User Configuration 으로 mcp.json 을 열어 같은 내용을 넣거나, 터미널에서 code --add-mcp '{"name":"tistory","type":"stdio","command":"uvx","args":["tistory-mcp"]}' 를 실행합니다. 위의 "Install in VS Code" 버튼도 같은 일을 합니다.

Codex CLI

codex mcp add tistory -- uvx tistory-mcp

또는 ~/.codex/config.toml:

[mcp_servers.tistory]

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

Codex 의 도구 호출 제한(tool_timeout_sec)은 기본 60초라 브라우저 로그인이 그 안에 끝나기 어렵습니다. 같은 테이블에 tool_timeout_sec = 600 을 두거나, 터미널에서 tistory-mcp login myblog.tistory.com 으로 먼저 로그인해 두세요.

Gemini CLI

gemini mcp add -s user tistory uvx tistory-mcp

또는 ~/.gemini/settings.json (프로젝트는 .gemini/settings.json):

{

"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 로 글이 생겼는지 먼저 확인하세요. 서버는 호출마다 새 글을 만듭니다.

환경변수

| `TI