hatena-blog-mcp

MCP-сервер для создания и обновления записей в Hatena Blog. Тонкая обёртка над はてなブログ AtomPub API, позволяющая AI-агенту работать с черновиками, редактированием и публикацией записей.

Установка

В качестве менеджера пакетов используется pnpm (зафиксирован в поле packageManager).

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

Получение значений настроек

В [Настройки] > [Дополнительные настройки] > [AtomPub] отображаются «Корневая конечная точка» и «API-ключ». Корневая конечная точка имеет следующий вид:

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

• Если блог принадлежит вам, владелец и оператор совпадают, поэтому HATENA_BLOG_OWNER_ID не нужен.

• В общем блоге (например, корпоративном техническом блоге) владелец и оператор различаются. В этом случае укажите ID владельца блога в HATENA_BLOG_OWNER_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 (API-ключ будет записан в .mcp.json).

Если записывать напрямую в файл конфигурации:

{
  "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 доступны в том же виде, что и для записей. Статические страницы доступны только на платном тарифе Hatena Blog (на бесплатном тарифе возвращается 404). Статические страницы не имеют категорий, поэтому параметр categories отсутствует.

Проектные решения

Удаление не реализовано

Удаление записей и статических страниц (DELETE) есть на стороне API, но намеренно не предоставлено как инструмент. Потому что последствия ошибочного действия велики и их нельзя отменить. Удаление выполняется через браузер.

update_entry — дифференциальное обновление

Поскольку PUT в AtomPub «заменяет всё отправленным содержимым», даже если вы хотите исправить только заголовок, необходимо заново отправить текст, категории и дату публикации. Этот сервер в update_entry сначала выполняет GET, затем заменяет только указанные поля и отправляет PUT.

• Пропущенные поля сохраняют текущие значения.

• Если опустить updated, дата публикации записи (отображаемая дата) не изменится.

• Если передать categories, произойдёт замена (не добавление). Чтобы сохранить существующие категории, передайте их вместе с новыми.

Новые записи по умолчанию черновик

Параметр draft в create_entry по умолчанию равен 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 Hatena Blog возвращает небольшое количество записей на страницу, и количество определяется на стороне API (в официальной документации указано 7 записей, но фактически возвращается 10). list_entries возвращает одну страницу, а передача next_page в параметр page следующего вызова позволяет получить продолжение. Для поиска по всем записям используйте search_entries, который внутри переходит по страницам. Количество просматриваемых страниц контролируется параметром max_pages.

Аутентификация и Hatena ID в URL

Используется аутентификация WSSE (заголовок X-WSSE). Для каждого запроса генерируются Nonce и Created, а Base64(SHA1(Nonce + Created + API-ключ)) отправляется как PasswordDigest.

Обратите внимание: Hatena ID в URL конечной точки (владелец блога) и аккаунт для аутентификации — это разные вещи. API-ключ выдаётся не для блога, а для аккаунта, поэтому в общем блоге

• URL: https://blog.hatena.ne.jp/{所有者のID}/{ブログID}/atom

• Аутентификация: Hatena ID вашего аккаунта + API-ключ

Получается такая комбинация. Если их перепутать, возникнет 401 (ключ не принадлежит владельцу) или 403 (у аккаунта нет прав на блог). Этот сервер разделяет их через HATENA_BLOG_OWNER_ID и HATENA_ID, а при отсутствии значения обрабатывает их как один и тот же ID, поэтому он работает одинаково и для собственного блога, и для общего.

Вне области действия

• Загрузка изображений: вне области AtomPub (есть отдельный はてなフォトライフ API)

• Изменение макета статических страниц: не поддерживается API. Настраивается через браузер

• OAuth-аутентификация: поддерживается только WSSE-аутентификация с API-ключом

Разработка

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

pnpm 10 по умолчанию блокирует скрипты сборки зависимостей, поэтому только esbuild, используемый tsx, разрешён в pnpm.onlyBuiltDependencies в package.json.

Структура

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, поэтому registerCollectionTools из tools/collection.ts вызывается с двумя разными настройками: для записей и для статических страниц.

Лицензия

MIT License. Подробнее см. LICENSE.