Shirabe Calendar API

日本の暦情報（六曜・暦注・干支・二十四節気）と用途別吉凶判定を返す REST API + MCP サーバー。

AIエージェント（Claude、ChatGPT 等）が直接呼び出せる MCP 対応と、コンテキスト付きレスポンスが特長です。

クイックスタート

1. APIキーを取得

shirabe.dev でアカウントを作成し、APIキーを取得してください（Free プランは月1,000リクエストまで無料）。

2. APIを呼び出す

# 指定日の暦情報を取得
curl -H "X-API-Key: shrb_your_api_key" \
  "https://api.shirabe.dev/api/v1/calendar/2026-11-15"

# 結婚式に最適な日を検索
curl -H "X-API-Key: shrb_your_api_key" \
  "https://api.shirabe.dev/api/v1/calendar/best-days?purpose=wedding&start=2026-11-01&end=2027-03-31&limit=5"

# 日付範囲の大安を一括取得
curl -H "X-API-Key: shrb_your_api_key" \
  "https://api.shirabe.dev/api/v1/calendar/range?start=2026-11-01&end=2026-11-30&filter_rokuyo=大安"

3. MCP で使う（Claude Desktop）

方法 A: npm パッケージ（推奨）

npm install -g @shirabe/calendar-mcp

claude_desktop_config.json に以下を追加:

{
  "mcpServers": {
    "shirabe-calendar": {
      "command": "npx",
      "args": ["-y", "@shirabe/calendar-mcp"],
      "env": {
        "SHIRABE_API_KEY": "shrb_your_api_key"
      }
    }
  }
}

方法 B: リモート MCP サーバー（URL 直接指定）

Streamable HTTP 対応のクライアントでは URL を直接指定できます:

{
  "mcpServers": {
    "shirabe-calendar": {
      "url": "https://shirabe.dev/mcp"
    }
  }
}

設定後、Claude に「明日の六曜は？」「来月の結婚式に最適な日は？」と聞くだけで暦情報を取得できます。

API エンドポイント

GET /api/v1/calendar/{date}

指定日の暦情報をすべて返します。

| パラメータ | 型 | 必須 | 説明 | |-----------|------|------|------| | date | path (YYYY-MM-DD) | Yes | 対象日付 | | categories | query (カンマ区切り) | No | 吉凶判定カテゴリ（省略時は全カテゴリ） | | lang | query | No | ja（デフォルト）または en |

GET /api/v1/calendar/range

日付範囲の暦情報を一括取得します。

| パラメータ | 型 | 必須 | 説明 | |-----------|------|------|------| | start | query (YYYY-MM-DD) | Yes | 開始日 | | end | query (YYYY-MM-DD) | Yes | 終了日（最大93日間） | | filter_rokuyo | query | No | 六曜フィルタ（例: 大安） | | filter_rekichu | query | No | 暦注フィルタ（例: 天赦日） | | category | query | No | カテゴリフィルタ（例: wedding） | | min_score | query | No | 最低スコア（1〜10） |

GET /api/v1/calendar/best-days

指定用途に最適な日をランキングで返します。

| パラメータ | 型 | 必須 | 説明 | |-----------|------|------|------| | purpose | query | Yes | 用途（wedding / funeral / moving / construction / business / car_delivery / marriage_registration / travel） | | start | query (YYYY-MM-DD) | Yes | 開始日 | | end | query (YYYY-MM-DD) | Yes | 終了日（最大365日間） | | limit | query | No | 返す件数（デフォルト5、最大20） | | exclude_weekdays | query | No | 除外曜日（例: 月,火） |

GET /health

ヘルスチェック。認証不要。

レスポンス例

単日取得

{
  "date": "2026-11-15",
  "wareki": "令和8年11月15日",
  "day_of_week": {
    "ja": "日曜日",
    "en": "Sunday"
  },
  "kyureki": {
    "year": 2026,
    "month": 10,
    "day": 1,
    "is_leap_month": false,
    "month_name": "神無月"
  },
  "rokuyo": {
    "name": "大安",
    "reading": "たいあん",
    "description": "終日吉。万事に良い日",
    "time_slots": {
      "morning": "吉",
      "noon": "吉",
      "afternoon": "吉",
      "evening": "吉"
    }
  },
  "kanshi": {
    "full": "丙辰",
    "jikkan": "丙",
    "junishi": "辰",
    "junishi_animal": {
      "ja": "龍",
      "en": "Dragon"
    }
  },
  "nijushi_sekki": {
    "name": "立冬",
    "reading": "りっとう",
    "description": "冬の始まり。冬の気配が立ち始める頃",
    "is_today": false
  },
  "rekichu": [
    {
      "name": "一粒万倍日",
      "reading": "いちりゅうまんばいび",
      "description": "始めたことが万倍に膨らむ吉日。開業・入籍・種まきに最適",
      "type": "吉"
    }
  ],
  "context": {
    "結婚": {
      "judgment": "大吉",
      "note": "大安と一粒万倍日が重なる最良の日。終日吉のため時間帯の制約もなし",
      "score": 10
    }
  },
  "summary": "大安と一粒万倍日が重なる大変縁起の良い日です。結婚式・入籍・開業など、新しいことを始めるのに最適です。"
}

MCP ツール

Shirabe Calendar API は以下の3つの MCP ツールを公開しています。

| ツール名 | 説明 | |---------|------| | get_japanese_calendar | 指定日の暦情報（六曜・暦注・干支・二十四節気）と吉凶判定を取得 | | find_best_days | 指定用途に最適な日を期間内から検索してランキングで返す | | get_calendar_range | 日付範囲の暦情報を一括取得（六曜・暦注でフィルタ可能） |

料金プラン

| プラン | 単価 | リクエスト/月 | レート制限 | |-------|------|-------------|-----------| | Free | 無料（月1,000回まで） | 1,000 | 1 req/s | | Starter | 1円/回（月1,000回まで無料） | 50,000 | 10 req/s | | Pro | 1円/回（月1,000回まで無料） | 500,000 | 50 req/s | | Enterprise | 1円/回（月1,000回まで無料） | 無制限 | 100 req/s |

プラン間の差別化は「月間リクエスト上限」と「レート制限」で行います。

認証

すべての API リクエストに X-API-Key ヘッダーが必要です（/health を除く）。

X-API-Key: shrb_a1b2c3d4e5f6...

レスポンスヘッダーにレート制限情報が含まれます:

X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 847
X-RateLimit-Reset: 2026-05-01T00:00:00Z

エラーレスポンス

{
  "error": {
    "code": "INVALID_DATE",
    "message": "Date must be in YYYY-MM-DD format and between 1873-01-01 and 2100-12-31",
    "details": { "received": "2026-13-01" }
  }
}

| ステータス | コード | 説明 | |-----------|-------|------| | 400 | INVALID_DATE | 日付形式が不正、または範囲外 | | 401 | INVALID_API_KEY | APIキーが無効または未指定 | | 429 | RATE_LIMIT_EXCEEDED | レート制限超過 | | 500 | INTERNAL_ERROR | サーバー内部エラー |

技術スタック

• ランタイム: Cloudflare Workers
• フレームワーク: Hono
• 言語: TypeScript (strict mode)
• MCP SDK: @modelcontextprotocol/sdk
• 課金: Stripe Billing
• KV: Cloudflare KV
• テスト: Vitest（171テスト）

ローカル開発

# 依存関係インストール
pnpm install

# 開発サーバー起動
pnpm run dev

# テスト実行
pnpm run test

# 型チェック
pnpm run typecheck

# npm パッケージ用 CLI ビルド
pnpm run build:cli

ライセンス

Proprietary. All rights reserved.

MCP クライアント連携のサンプルコードは MIT ライセンスで提供します。