ハルCMS 開発者ドキュメント

3つの入口

ハルCMSは、株式会社Web春が運営する日本語ファーストのヘッドレスCMSです。ブラウザのエディタに加えて、次の3つのプログラム向け入口を提供します。

• Markdownファースト — 本文は body_md（Markdown）だけ送ればOK。HTML変換はサーバー側で行います。
• 公開は即時 — status: "published" にした瞬間、配信APIに載ります。Webhook・CI設定は不要です。
• エディタと同一の検証 — API・MCP経由の操作もブラウザのエディタと同じ検証・変更履歴・監査ログを通ります。
• AI最適化 — MCP標準搭載・llms-full.txt 提供・下書き既定などの安全設計込み。

クイックスタート

0. APIキーを発行する

ダッシュボード（app.harucms.com）にログイン → 対象サイトの「APIキー」→ 用途がわかる名前を付けて発行します。キーの値が表示されるのは発行時の一度だけです（サーバーにはハッシュのみ保存）。停止・削除も同じ画面からいつでもできます。

1. 接続を確認する

コピーcurl https://app.harucms.com/api/ext/v1/me \
  -H "Authorization: Bearer hcms_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"

コピーconst BASE = "https://app.harucms.com/api/ext/v1";
const KEY = process.env.HARUCMS_API_KEY;

const res = await fetch(`${BASE}/me`, {
  headers: { Authorization: `Bearer ${KEY}` },
});
console.log(await res.json());

コピーimport os, requests

BASE = "https://app.harucms.com/api/ext/v1"
KEY = os.environ["HARUCMS_API_KEY"]

r = requests.get(f"{BASE}/me", headers={"Authorization": f"Bearer {KEY}"})
print(r.json())

コピー// レスポンス
{
  "ok": true,
  "data": {
    "site_name": "あなたのサイト名",
    "api_host": "your-site.harucms.app",
    "custom_domain": null,
    "collections": ["news"]
  }
}

2. 下書きを作る

コピーcurl -X POST "$BASE/posts" \
  -H "Authorization: Bearer $KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "夏季休業のお知らせ",
    "body_md": "## 休業期間\n\n8月13日〜16日はお休みをいただきます。",
    "category": "お知らせ"
  }'

status を省略すると必ず下書き（draft）として作成されます。サイトには載りません。

3. 公開する

コピーcurl -X PUT "$BASE/posts/作成された記事のidまたはslug" \
  -H "Authorization: Bearer $KEY" \
  -H "Content-Type: application/json" \
  -d '{ "status": "published" }'

認証とAPIキー

REST・MCP共通で、すべてのリクエストに以下のヘッダーが必要です。

キーの性質

• キーはサイトごとに発行され、そのサイトの記事・メディアだけを操作できます。他のサイト・アカウント設定・課金には一切アクセスできません。
• サーバー側にはキーのハッシュ（SHA-256）のみ保存されます。値が見られるのは発行時の一度だけです。紛失した場合は削除して再発行してください。
• キーの停止・削除は即時反映されます（以後の全リクエストは 401）。
• すべての操作はサイトの監査ログに記録されます（いつ・どのキーが・何をしたか）。
• キーを発行したメンバーをサイトから外すと、そのメンバーが発行したキーも自動で停止されます。

コンテンツモデル

コンテンツの単位は「記事（post）」です。記事は「コレクション」に属します（例: news = お知らせ、blog = ブログ）。コレクション名は半角英小文字・数字・-・_（1〜32文字）で、省略時は news。使用中の一覧は GET /me で確認できます。

記事のフィールド

slugのルール: 半角英数字で始まり、英数字と - _ . だけが使えます（120文字以内）。SEOを意識するなら英小文字とハイフンでの明示指定を推奨します。

公開ステータスの遷移

公開中の記事を draft に戻すと、配信APIからも取り下げられます。保存のたびに変更履歴が自動で残り、エディタから復元できます。

SEO設定（seoフィールド）

作成・更新時に seo オブジェクトを渡すと、記事単位のSEO・構造化データを設定できます。すべて任意です（設定するものだけ入れる）。

検証はサーバー側で行われ、不正な形のフィールドは黙って捨てられます（エラーにはなりません）。更新時に seo を省略すると既存値を維持、null を送るとクリアします。

配信API（公開・キー不要）

サイト側（Astro・Next.js等）から公開記事を取得するAPIです。認証不要・CORS全開放なので、ブラウザからもビルド時からも直接fetchできます。公開済み（published）の記事だけが返ります。

自分のサイトの配信ホストは GET /me の api_host、またはダッシュボードのサイトカードで確認できます。

Astro / Next.js から取得する

Astro（ビルド時取得＝静的生成）

コピー---
// src/pages/news/index.astro
const res = await fetch('https://your-site.harucms.app/v1/posts?limit=20');
const { posts } = await res.json();
// 詳細ページは /v1/posts/{slug}（getStaticPathsで全slugを列挙して生成）
---
<ul>
  {posts.map((p) => (
    <li><a href={`/news/${p.slug}/`}>{p.title}</a></li>
  ))}
</ul>

Next.js（App Router・ISR）

コピー// app/news/page.tsx
export const revalidate = 300;

export default async function NewsPage() {
  const res = await fetch('https://your-site.harucms.app/v1/posts?limit=20', {
    next: { revalidate: 300 },
  });
  const { posts } = await res.json();
  return (
    <ul>
      {posts.map((p: { id: string; slug: string; title: string }) => (
        <li key={p.id}><a href={`/news/${p.slug}`}>{p.title}</a></li>
      ))}
    </ul>
  );
}

MCPサーバー

MCP（Model Context Protocol）は、AIアシスタントに外部ツールを安全に接続するための標準プロトコルです。ハルCMSはホスト型MCPサーバーを標準搭載しており、npm installもコードも不要で、AIに「記事を書いて下書きにして」と話すだけで動きます。

Claude Code（CLI）

コピーclaude mcp add --transport http haru-cms https://app.harucms.com/mcp \
  --header "Authorization: Bearer hcms_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"

登録後、Claudeに「サイトにお知らせを1本書いて下書きにして」のように話すだけで動きます。

Claude Desktop

設定 → コネクタ → 「カスタムコネクタを追加」で上記URLを入力し、ヘッダーに Authorization: Bearer hcms_... を設定します。

Cursor / その他のMCPクライアント

コピー// mcp.json（Cursor: .cursor/mcp.json）
{
  "mcpServers": {
    "haru-cms": {
      "url": "https://app.harucms.com/mcp",
      "headers": { "Authorization": "Bearer hcms_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" }
    }
  }
}

ChatGPT

お使いのChatGPTのコネクタ設定がヘッダー認証（Bearer）に対応していれば、上記URL＋Authorization: Bearer hcms_... で登録できます。ヘッダー指定ができないプラン・バージョンでは、REST APIをそのまま使ってください（llms-full.txt を読ませれば連携コードの実装まで自走します）。

MCPツールリファレンス

提供しているツールは以下の8本だけです（これ以外の名前のツールは存在しません）。

安全設計

• 既定は下書き — status を明示しない作成は必ず下書きになります。AIが会話の流れで勝手に公開することはありません。
• スコープはサイト単位 — キーは1サイト分の権限しか持ちません。他サイト・アカウント設定・課金には一切アクセスできません。
• 全操作が監査ログに記録 — いつ・どのキーが・どの記事に何をしたかをダッシュボードで確認できます。
• 即時失効 — キーを停止・削除すればその瞬間からすべての操作が拒否されます。
• HTMLはサニタイズ — body_html を直接送ってもサーバー側でサニタイズされます（XSS対策）。

エラーとプラン制限

エラーは共通フォーマット { "error": "日本語のメッセージ" } ＋ HTTPステータスで返ります。

レート制限とリクエスト枠

• 分単位の固定レート制限は現在ありません（429 は返りません）。ただしバッチ処理は1〜2リクエスト/秒程度に抑えるのが行儀の良い使い方です。
• プランには月間リクエスト枠があります（配信API＋REST/MCPの合算。Free 100万〜Business 2億）。枠を超えてもAPIも配信も止まりません。超過分は100円/100万リクエスト（税込）で自動継続します。
• ストレージ上限（プラン別）を超えると新規アップロードだけがブロックされます。既存の記事・画像・配信には影響しません。
• 最新の料金・制限は機械可読のJSONでも取得できます（認証不要）: /api/public/pricing

AIエージェント連携

このドキュメントの全文はAIが読み込みやすいプレーンテキストでも提供しています。AIエージェント（Claude Code等）に以下を渡すだけで、連携コードの実装やMCPセットアップから記事作成まで自走できます。

コピーhttps://app.harucms.com/docs/llms-full.txt を読んで、
ハルCMSとの連携をセットアップしてください。
APIキー: 環境変数 HARUCMS_API_KEY に設定済み
やりたいこと: （例）毎週月曜にブログ下書きを自動生成する

例えばこんな依頼がそのまま動きます:

• 「MCPで接続して、今公開中の記事一覧を見せて」
• 「この議事録を要約してお知らせ記事の下書きにして」
• 「予約投稿で来週月曜9時に公開される記事を作って」
• 「この画像URLを取り込んで表紙にした記事を作って」

よくある質問

Webhookはありますか？

あります。管理画面の「サイト設定 → Webhook」で通知先URLを登録すると、記事の公開・更新・非公開・削除の瞬間に POST で通知します（1サイト5件まで・HMAC署名 x-harucms-signature 付き・届かないときは1分→5分→30分→120分で再試行）。ペイロードは記事のメタ（id・slug・title・status・published_at）だけで、本文は配信APIから取り直してください。

いちばん簡単な使い方は、ホスティングのデプロイフックURLをそのまま登録することです。Vercel・Netlify・Cloudflare Pages はいずれも「POSTが来たら再ビルド」するURLを発行しており、追加の設定は要りません。GitHub Actions でデプロイしている場合はフックURLが無いので、署名を検証して repository_dispatch を叩く小さな受け口を1本用意します（webharu.com はこの方式）。

読み取り専用のキーはありますか？

現在のキーは読み書き両方の権限を持ちます。取得だけの用途ならAPIキーは不要です — 公開記事は配信API（キー不要）で取得できます。下書きも読む必要がある場合だけキーを使ってください。

body_htmlを直接送ってもいい？

可能ですが推奨しません。body_md だけ送る方が、エディタとの相互編集・将来のデザイン変更に強くなります。送ったHTMLはサーバー側でサニタイズされます。

予約公開の精度は？

5分間隔のスケジューラが処理するため、指定時刻から最大5分程度の遅延があります。公開日時には予約時刻がそのまま記録されます。

公開したのにサイトに反映されない

配信APIのエッジキャッシュ（約5分）の可能性があります。5分待っても反映されない場合は、取得しているホスト（api_host）とコレクション名を確認してください。Astroの静的生成では再ビルドも必要です。

1つのキーを複数のツールで使い回してもいい？

動作はしますが、ツールごとにキーを分けることを推奨します（監査ログでの区別・漏えい時に該当ツールだけ止められるため）。

記事数の上限は？

全プラン無制限です。プランで変わるのはサイト数・メンバー数・ストレージ・月間リクエスト枠です（料金データ）。

独自ドメインで配信できる？

有料プランで独自ドメインを設定できます。検証完了後は https://あなたのドメイン/v1/posts と、同じパス構成で配信されます。