네이버 블로그 MCP 서버

Playwright 기반 네이버 블로그 자동화를 위한 Model Context Protocol (MCP) 서버입니다. Claude가 네이버 블로그에 글을 작성하고 관리할 수 있도록 합니다.

📋 프로젝트 개요

네이버 블로그의 공식 API가 2020년에 종료됨에 따라, Playwright 웹 브라우저 자동화를 활용하여 MCP (Model Context Protocol) 서버를 구현합니다. AI 어시스턴트(Claude 등)가 네이버 블로그에 글을 작성할 수 있도록 지원합니다.

✨ 주요 기능

• ✅ 네이버 로그인 자동화 (세션 저장/재사용)
• ✅ MCP 서버 구현 (Claude Desktop 연동)
• ✅ 네이버 블로그 글 작성 (제목, 본문, 발행)
• ✅ 이미지 업로드 (파일/Base64, 단일/다중, 7개 포맷 지원)
• ✅ 에러 처리 및 재시도 (네트워크 에러 자동 복구, UI 변경 대응)
• ✅ 디버깅 도구 (Playwright Trace, 자동 스크린샷)
• ✅ 카테고리 조회 (블로그 카테고리 목록)

🛠️ 기술 스택

• Python 3.13
• Playwright 1.55.0 - 웹 브라우저 자동화
• MCP SDK - Model Context Protocol
• Pydantic - 데이터 검증
• Tenacity - 재시도 로직

📦 설치

1. 저장소 클론

git clone https://github.com/space-cap/naver-blog-mcp.git
cd naver-blog-mcp

2. 의존성 설치

# uv를 사용하여 의존성 설치
uv sync

# Playwright 브라우저 다운로드 (필수!)
uv run playwright install chromium

3. 환경 변수 설정

# .env.example을 .env로 복사
cp .env.example .env

# .env 파일 편집
# NAVER_BLOG_ID와 NAVER_BLOG_PASSWORD를 입력하세요

.env 파일 예시:

# 네이버 블로그 계정 정보
NAVER_BLOG_ID=your_naver_id
NAVER_BLOG_PASSWORD=your_password

# Playwright 설정
HEADLESS=false  # 디버깅 시 false로 설정
SLOW_MO=100     # 액션 사이 딜레이 (ms)

# 로깅 레벨
LOG_LEVEL=INFO

🚀 사용 방법

방법 1: Claude Desktop과 연동 (권장)

Claude Desktop 설정 파일(claude_desktop_config.json)에 다음 추가:

{
  "mcpServers": {
    "naver-blog": {
      "command": "uv",
      "args": ["run", "naver-blog-mcp"],
      "cwd": "C:\\workdir\\space-cap\\naver-blog-mcp",
      "env": {
        "PYTHONIOENCODING": "utf-8"
      }
    }
  }
}

Claude Desktop 재시작 후 다음과 같이 사용:

네이버 블로그에 글을 작성해줘.
제목: MCP 테스트
내용: Claude가 작성한 첫 번째 글!

방법 2: 직접 실행

# MCP 서버 실행
uv run naver-blog-mcp

방법 3: 테스트 스크립트

# 서버 초기화 테스트
uv run python tests/test_server.py

# Tool 핸들러 테스트 (실제 글 작성)
uv run python tests/test_tools.py

# 통합 테스트 (전체)
uv run python tests/test_integration.py

📁 프로젝트 구조

naver-blog-mcp/
├── src/
│   └── naver_blog_mcp/
│       ├── server.py              # ✅ MCP 서버 메인
│       ├── config.py              # ✅ 설정 관리
│       ├── automation/            # Playwright 자동화
│       │   ├── login.py          # ✅ 로그인 자동화
│       │   ├── post_actions.py   # ✅ 글쓰기 자동화
│       │   └── selectors.py      # ✅ DOM 셀렉터
│       ├── services/              # 비즈니스 로직
│       │   └── session_manager.py # ✅ 세션 관리
│       ├── mcp/                   # MCP 프로토콜
│       │   └── tools.py          # ✅ Tool 정의 및 핸들러
│       ├── models/                # 데이터 모델
│       └── utils/                 # 유틸리티
├── tests/
│   ├── test_server.py            # ✅ 서버 초기화 테스트
│   ├── test_tools.py             # ✅ Tool 핸들러 테스트
│   └── test_integration.py       # ✅ 통합 테스트
├── docs/
│   ├── architecture.md           # 아키텍처 설계서
│   ├── implementation-plan.md    # 구현 계획서
│   ├── progress.md               # 진행 상황
│   └── user-guide.md             # ✅ 사용자 가이드
└── playwright-state/             # 세션 저장 (Git 무시)

📊 개발 진행 상황

Phase 1 완료: 93% (Day 13/14 완료)

Phase 1 (Week 1-2): █████████████░ 93%
Phase 2 (Week 3):   ░░░░░░░░░░░░░░  0%
Phase 3 (Week 4):   ░░░░░░░░░░░░░░  0%

전체 프로젝트:     █████████████░ 52%

완료된 마일스톤

• ✅ Day 1-3: 프로젝트 초기 설정 및 기본 자동화
• ✅ Day 5-7: MCP 서버 및 핵심 Tool 구현
• ✅ Day 8-10: 에러 처리 및 재시도 로직
  • 커스텀 예외 클래스, Playwright 에러 핸들러
  • tenacity 재시도 (지수 백오프)
  • Playwright Trace 자동 기록
• ✅ Day 11-12: 이미지 업로드 기능
  • 파일/Base64 업로드, 단일/다중 이미지
  • 7개 포맷 지원 (JPG, PNG, GIF, BMP, HEIC, HEIF, WebP)
  • 10MB 크기 제한, 자동 에러 처리
• ✅ Day 13: 카테고리 목록 조회 및 MCP 서버 연동
  • Claude Desktop 연동 문서 작성
  • MCP 서버 인코딩 오류 수정
  • 카테고리 목록 조회 기능 완전 구현

알려진 제한 사항

• ❌ Day 14: Markdown 지원 (구현 불가)
  • 네이버 블로그는 Markdown을 지원하지 않음
  • HTML 편집 모드도 스마트에디터 ONE으로 통합되면서 제거됨

자세한 진행 상황은 docs/progress.md를 참고하세요.

🎯 사용 가능한 MCP Tools

1. naver_blog_create_post

블로그에 새 글을 작성합니다.

파라미터:

• title (필수): 글 제목
• content (필수): 글 본문
• category (선택): 카테고리 이름
• tags (선택): 태그 배열
• images (선택): 이미지 파일 경로 배열
• publish (선택): 즉시 발행 여부 (기본: true)

2. naver_blog_list_categories

블로그의 카테고리 목록을 조회합니다.

파라미터: 없음

🔧 개발

테스트 실행

# 모든 테스트
uv run pytest tests/ -v

# 로그인 테스트
uv run python tests/test_login.py

# 글쓰기 테스트
uv run python tests/test_post_write.py

코드 포매팅

# Black 포매팅
uv run black src/ tests/

# Ruff 린팅
uv run ruff check src/ tests/

# Mypy 타입 체킹
uv run mypy src/

Playwright 디버깅

# Inspector 모드
PWDEBUG=1 uv run python tests/test_post_write.py

# 헤드 모드 (브라우저 보이기)
HEADLESS=false uv run python tests/test_post_write.py

# 느린 모드 (액션 사이 딜레이)
SLOW_MO=500 uv run python tests/test_post_write.py

⚠️ 주의사항

CAPTCHA

• 헤드리스 모드에서 CAPTCHA가 발생할 수 있습니다
• HEADLESS=false로 설정하면 수동으로 CAPTCHA를 풀 수 있습니다

네이버 이용약관

• 과도한 자동화 사용 자제
• 스팸성 콘텐츠 게시 금지
• 정상적인 사용 패턴 유지

세션 관리

• 세션은 최대 24시간 유효
• playwright-state/ 폴더는 절대 Git에 커밋하지 마세요
• .env 파일도 Git에 커밋하지 마세요

📚 문서

사용자용

• 배포 가이드 - 설치 및 배포 완전 가이드 ⭐
• 설치 가이드 - 상세 설치 방법
• Claude Desktop 가이드 - Claude Desktop 연동
• 사용자 가이드 - 사용 방법 및 예제

개발자용

• 아키텍처 설계서 - 상세 시스템 아키텍처
• 구현 계획서 - 4주 구현 로드맵
• 진행 상황 - 프로젝트 진행 현황

🎯 사용 예시

예시 1: 간단한 글 작성

Claude에게 다음과 같이 요청:

네이버 블로그에 글을 써줘.
제목: 오늘의 개발 일지
내용: MCP 서버를 사용해서 자동으로 글을 작성했다. 정말 편리하다!

예시 2: 기술 블로그 작성

Playwright의 장점에 대한 기술 블로그를 작성해줘.
제목은 "Playwright로 웹 자동화 시작하기"로 하고,
Selenium과의 비교, 코드 예제를 포함해줘.

예시 3: 마크다운 형식

다음 마크다운을 네이버 블로그 글로 작성해줘:

제목: Python asyncio 입문

# asyncio란?
Python의 비동기 프로그래밍 라이브러리입니다.

## 주요 개념
- Event Loop
- Coroutines
- Tasks

🤝 기여

이슈 및 PR을 환영합니다!

📄 라이선스

MIT License

📞 문의

GitHub Issues를 통해 문의해주세요.

🤖 Generated with Claude Code