hatena-blog-mcp

하테나 블로그의 글을 작성·업데이트하기 위한 MCP 서버. 하테나 블로그 AtomPub API를 얇게 래핑하여, AI 에이전트에서 글의 초안·퇴고·공개를 다룰 수 있게 한다.

셋업

패키지 매니저는 pnpm을 사용한다(packageManager 필드로 고정).

pnpm install   # 依存のインストールと同時に prepare で dist がビルドされる

설정값 취득

하테나 블로그의 **[설정] > [상세 설정] > [AtomPub]**에 「루트 엔드포인트」와 「API 키」가 표시된다. 루트 엔드포인트는 다음 형식이다.

https://blog.hatena.ne.jp/{ブログ所有者のはてなID}/{ブログID}/atom

• 자신이 소유한 블로그라면 소유자와 조작자가 같으므로 HATENA_BLOG_OWNER_ID는 불필요

• 공유 블로그(회사 테크 블로그 등)에서는 소유자와 조작자가 다르다. 이 경우 HATENA_BLOG_OWNER_ID에 블로그 소유자의 ID를, HATENA_ID에는 자신의 계정을 지정한다

• 유료 플랜으로 독자 도메인을 사용하는 경우에도 HATENA_BLOG_ID는 독자 도메인 설정 전의 도메인을 지정한다

.env.example 참조.

MCP 클라이언트 등록

Claude Code의 경우:

# 自分が所有するブログ
claude mcp add hatena-blog -s user \
  -e HATENA_ID=your-hatena-id \
  -e HATENA_BLOG_ID=your-blog.hatenablog.com \
  -e HATENA_API_KEY=your-api-key \
  -- node /absolute/path/to/hatena-blog-mcp/dist/index.js

# 共有ブログ（所有者と操作者が異なる場合は HATENA_BLOG_OWNER_ID を足す）
claude mcp add hatena-blog -s user \
  -e HATENA_ID=your-hatena-id \
  -e HATENA_BLOG_OWNER_ID=blog-owner-id \
  -e HATENA_BLOG_ID=blog-owner-id.hatenablog.com \
  -e HATENA_API_KEY=your-api-key \
  -- node /absolute/path/to/hatena-blog-mcp/dist/index.js

-s user를 붙이면 모든 프로젝트에서 사용할 수 있다. -s project는 사용하지 말 것(.mcp.json에 API 키가 기록된다).

설정 파일에 직접 작성하는 경우:

{
  "mcpServers": {
    "hatena-blog": {
      "command": "node",
      "args": ["/absolute/path/to/tech-blog/dist/index.js"],
      "env": {
        "HATENA_ID": "your-hatena-id",
        "HATENA_BLOG_OWNER_ID": "blog-owner-id",
        "HATENA_BLOG_ID": "blog-owner-id.hatenablog.com",
        "HATENA_API_KEY": "your-api-key"
      }
    }
  }
}

등록이 완료되면 get_blog_info를 호출하면 통신 확인이 된다.

Related MCP server: Blogger MCP Server

도구

블로그 전체

글

고정 페이지

list_pages / search_pages / get_page / create_page / update_page가 글과 같은 형태로 준비되어 있다. 고정 페이지는 하테나 블로그의 유료 플랜에서만 이용할 수 있다(무료 플랜에서는 404가 반환된다). 고정 페이지는 카테고리를 갖지 않으므로 categories 파라미터는 없다.

설계상의 결정 사항

삭제는 구현하지 않음

글·고정 페이지의 삭제(DELETE)는 API 쪽에 있지만, 의도적으로 도구로 공개하지 않았다. 오조작의 영향이 크고, 취소할 수 없기 때문이다. 삭제는 브라우저에서 수행한다.

update_entry는 차분 업데이트

AtomPub의 PUT은 「보낸 내용으로 전체를 교체」하므로, 제목만 고치려 해도 본문·카테고리·게시 일시를 모두 다시 보내야 한다. 이 서버는 update_entry 안에서 GET한 후 지정된 항목만 교체하여 PUT한다.

• 생략한 항목은 현재 값이 그대로 유지된다

• updated를 생략하면 글의 게시 일시(표시되는 날짜)는 변하지 않는다

• categories를 전달한 경우에는 교체가 된다(추가가 아님). 기존 카테고리를 유지하고 싶을 때는 기존분도 포함해서 전달한다

신규 작성은 기본적으로 초안

create_entry의 draft는 기본 true. 에이전트의 조작으로 갑자기 글이 공개되는 것을 피하기 위해, 공개는 명시적으로 draft: false를 지정했을 때만 이루어진다.

본문 문법

content_type에는 text/x-markdown / text/x-hatena-syntax / text/html / text/plain을 지정할 수 있다(기본은 text/x-markdown). 단, 실제로 어떻게 해석되는지는 블로그 측의 「편집 모드」 설정에 따른다ため, 블로그 설정과 맞춰서 작성해야 한다. 기존 글의 업데이트에서는 편집 전의 문법이 계승된다.

예약 게시

create_entry에서 draft: true + scheduled: true + 미래 시각의 updated를 지정한다.

목록 페이지네이션

하테나 블로그의 API는 1페이지당 건수가 적고, 건수는 API 측에서 결정된다 (공식 문서는 글 7건이라고 기재되어 있지만, 실제로는 10건이 반환되는 것을 확인했다). list_entries는 1페이지분을 반환하고, next_page를 다음 호출의 page에 전달하면 이어서 취득할 수 있다. 한꺼번에 찾고 싶을 때는 내부에서 페이지를 따라가는 search_entries를 사용한다. max_pages로 탐색량을 제어한다.

인증과 URL의 하테나 ID

WSSE 인증(X-WSSE 헤더)을 사용한다. 요청마다 Nonce와 Created를 생성하고, Base64(SHA1(Nonce + Created + API키))를 PasswordDigest로 보낸다.

엔드포인트 URL의 하테나 ID(블로그 소유자)와 인증하는 계정은 별개라는 점에 주의. API 키는 블로그 단위가 아니라 계정 단위로 발급되므로, 공유 블로그에서는

• URL: https://blog.hatena.ne.jp/{소유자의 ID}/{블로그ID}/atom

• 인증: 자신의 계정의 하테나 ID + API 키

라는 조합이 된다. 둘을 혼동하면 401(키가 소유자의 것이 아님)이나 403(그 계정에 블로그 권한이 없음)이 된다. 이 서버는 HATENA_BLOG_OWNER_ID와 HATENA_ID로 둘을 분리하고 있으며, 생략 시에는 동일 ID로 취급하므로 자신의 블로그든 공유 블로그든 같은 설정 방법으로 동작한다.

범위 외

• 이미지 업로드: AtomPub의 범위 외(하테나 포토라이프 API가 별도로 있음)

• 고정 페이지의 레이아웃 변경: API 미지원. 브라우저에서 설정한다

• OAuth 인증: API 키에 의한 WSSE 인증만 지원

개발

pnpm run typecheck   # 型チェック
pnpm test            # ユニットテスト（API はモック）
pnpm run build       # dist へビルド
pnpm run dev         # ビルドせずに起動
pnpm run inspect     # MCP Inspector で手動確認

pnpm 10은 의존성의 빌드 스크립트를 기본적으로 차단하므로, tsx가 사용하는 esbuild만을 package.json의 pnpm.onlyBuiltDependencies에서 허용하고 있다.

구성

src/
  index.ts          エントリポイント（stdio トランスポート）
  server.ts         McpServer の組み立て
  config.ts         環境変数の読み込み
  hatena/
    client.ts       AtomPub の HTTP クライアント
    wsse.ts         WSSE 認証ヘッダの生成
    atom.ts         Atom XML のパース・生成
    types.ts        ドメイン型
  tools/
    blog.ts         ブログ全体に対するツール
    collection.ts   記事・固定ページ共通のツール定義
    shared.ts       ツールの共通ヘルパー

글과 고정 페이지는 AtomPub상 거의 같은 구조이므로, tools/collection.ts의 registerCollectionTools를 글용·고정 페이지용의 2가지 설정으로 나누어 호출하고 있다.

라이선스

MIT License. 자세한 내용은 LICENSE를 참조.