velocms

@velocms/mcp

VeloCMS 用の MCP サーバーです。 Claude Code、Claude Desktop、Cursor、その他の MCP クライアントから、ブログ（投稿、メディア、コメント、メンバー、サイト設定）の下書き作成、編集、公開、管理を行えます。

VeloCMS Public API（https://<your-blog>/api/v1。VeloCMS サイトの /api/openapi にドキュメントが記載されています）を薄く型付きでラップしています。各ツールは実際の API 呼び出しに対応し、Zod による入力検証と読みやすいエラーを備えています。スクレイピングやブラウザーの自動操作は行わず、プラットフォームがサポートする REST API のみを使用します。

できること

ツール	できること
list_posts	投稿をページ分割して一覧表示します。ステータス（draft／published）による絞り込みも可能です
get_post	ID を指定して単一の投稿を取得します。本文全体と SEO フィールドも含まれます
create_post	新しい投稿を作成します（デフォルトは draft）
update_post	既存の投稿を部分的に更新します。渡したフィールドのみが変更されます
delete_post	投稿を完全に削除します
publish_post	投稿のステータスを published に設定します（published_at が記録されます）
unpublish_post	投稿のステータスを draft に戻します
list_media	メディアライブラリをページ分割して一覧表示します。MIME タイプによる絞り込みも可能です
list_comments	コメントをページ分割して一覧表示します。投稿またはモデレーションのステータスによる絞り込みも可能です
moderate_comment	コメントのステータスを approved、pending、または spam に設定します
list_members	購読者／読者を一覧表示します（メールアドレスは u***@example.com のようにマスキングされます）
get_site_settings	ブログの名前、説明、機能フラグを読み取ります

各ツールには、LLM が使いどころと使い方を判断するための説明が含まれています。余計な手順を加えた REST プロキシではなく、これこそが MCP の役割です。 引数の一覧は、以下のツールリファレンスをご覧ください。

セットアップ

1. VeloCMS API キーを取得する

VeloCMS ダッシュボードで、Settings → API Keys に移動し、必要なスコープ（posts:read、posts:write、media:read、comments:read、 comments:moderate、members:read、site-settings:read など）を指定してキーを作成します。API アクセスには Pro プラン以上が必要です。

2. MCP クライアントを設定する

このリポジトリをクローンする必要はありません。npx が必要に応じて取得し、実行します。

Claude Code

claude mcp add velocms \
  --env VELOCMS_SITE_URL=https://myblog.velocms.org \
  --env VELOCMS_API_KEY=velo_your_64_char_hex_key_here \
  -- npx -y -p @velocms/mcp velocms-mcp

MCP サーバーのツールはセッション開始時に登録されるため、設定を追加した後に Claude Code のセッションを再起動してください。

Claude Desktop

claude_desktop_config.json に追加します（Settings → Developer → Edit Config）。

{
  "mcpServers": {
    "velocms": {
      "command": "npx",
      "args": ["-y", "-p", "@velocms/mcp", "velocms-mcp"],
      "env": {
        "VELOCMS_SITE_URL": "https://myblog.velocms.org",
        "VELOCMS_API_KEY": "velo_your_64_char_hex_key_here"
      }
    }
  }
}

編集後、Claude Desktop を再起動してください。

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

上記と同様の形式で、クライアントの MCP 設定から npx -y -p @velocms/mcp velocms-mcp を指定し、env に VELOCMS_SITE_URL と VELOCMS_API_KEY を設定します。このサーバーは標準的な MCP over stdio で通信するため、stdio MCP サーバーに対応するクライアントであれば使用できます。

3. ローカルインストール（コントリビューション／ソースから実行する場合）

git clone https://github.com/VeloCMS/velocms-mcp.git
cd velocms-mcp
npm install
npm run build
cp .env.example .env
# edit .env and set VELOCMS_SITE_URL + VELOCMS_API_KEY
VELOCMS_SITE_URL=... VELOCMS_API_KEY=... node dist/index.js

設定リファレンス

環境変数	必須	説明
VELOCMS_SITE_URL	はい	ブログのベース URL です。*.velocms.org のサブドメイン、または紐付けたカスタムドメインを指定します。末尾のスラッシュは不要です。
VELOCMS_API_KEY	はい	/admin/settings → API Keys で取得した API キーです。Pro プラン以上が必要です。ログに記録されることはありません。

どちらかの設定が不足している場合、サーバーは標準エラー出力に明確なメッセージを表示して、直ちに終了します（process.exit(1)）。設定が不完全なまま起動することはありません。

ツールリファレンス

引数名は camelCase です。サーバーが API の snake_case JSON フィールドにマッピングします。

list_posts — page?、perPage?（最大 100）、status?（draft | published）。

get_post — id（必須）。

create_post — title（必須、≤255 文字）、slug?、contentHtml?、 contentJson?（TipTap ProseMirror ドキュメント。必要でない限り contentHtml を優先してください）、excerpt?（≤500）、status?（デフォルトは draft | published）、tags?（文字列配列）、seoTitle?（≤60）、 seoDescription?（≤160）。

update_post — id（必須）+ create_post の各フィールド （ここではすべて任意）。id 以外に少なくとも 1 つのフィールドが必須です。このツールは ネットワークリクエストを行う前に、変更のない呼び出しを拒否します。

delete_post — id（必須）。完全に削除します。

publish_post / unpublish_post — id（必須）。update_post({ status: "published" }) / update_post({ status: "draft" }) の簡略表記です。

list_media — page?、perPage?、type?（MIME タイプのプレフィックス。例： "image"）。

list_comments — page?、perPage?、postId?、status?（approved | pending | spam）。

moderate_comment — id（必須）、status（必須：approved | pending | spam）。

list_members — page?、perPage?、tier?（free | paid）。

get_site_settings — 引数なし。

エラー処理モデル

VeloCMS API は一貫した JSON エラーエンベロープを返します。

{ "error": { "code": "RATE_LIMITED", "message": "...", "details": {} } }

このクライアントはそのメッセージを直接表示し（生のスタックトレースは表示しません）、 実行可能なヒントを加えます。

• 401（UNAUTHORIZED）— メッセージで VELOCMS_API_KEY を確認するよう案内します。
• 403（PLAN_UPGRADE_REQUIRED）— メッセージで /admin/billing を案内します。
• 403（INVALID_SCOPE/FORBIDDEN）— メッセージでキーのスコープを確認するよう案内します。
• 429（RATE_LIMITED）— Retry-After レスポンスヘッダー（秒単位）を 解析してエラーメッセージに含めます。また、クライアントライブラリを直接呼び出している場合は retryAfterSeconds として返します。
• その他の 2xx 以外の応答 — API 独自の code と message をそのまま表示します。

レート制限はプランごとに設定されています（Pro：30/分、1,000/時間 · Business：120/分、 5,000/時間 · Agency：300/分、20,000/時間）。このサーバーは自動的に再試行せず、 待ち時間をすぐに通知して処理を失敗させるため、対話型のツール呼び出しが 通知なしにブロックされることはありません。

セキュリティ

• API キーは テナントスコープ の認証情報です。発行先のブログにのみアクセスでき、 アクセスできるのはスコープで許可されたエンドポイントに限られます。
• キーは環境変数から一度だけ読み込まれ、ログへの記録、エコー、ツール出力への 含有は一切行われません。
• list_members が返すメンバーのメールアドレスは API 自体によってマスクされます （例：u***@example.com）。このサーバーがマスクされていない メンバーの PII を見る、または扱うことはありません。
• 暗号化されたテナント設定（Stripe キー、AI プロバイダーのキー）は API によって get_site_settings の対象から除外されるため、このサーバーを通じて読み取る方法は ありません。

この MCP サーバーについての注意事項

• moderate_comment の本文フィールドは action ではなく status です — PATCH /api/v1/comments/{id}/moderate は API 独自のスキーマに従い、 { "status": "approved" | "pending" | "spam" } を受け取るため、ツールの入力名もそれに合わせています。
• get_post と get_site_settings はレコードを直接返します（ { "data": ... } でラップされません）。書き込みエンドポイント（create_post、 update_post、moderate_comment）のみレスポンスをラップします。この違いは API 自体の 一貫性のなさに合わせたもので、openapi.yaml に記載されています。
• 現在、upload_media ツールはありません — POST /api/v1/media は multipart/form-data を受け取りますが、一般的な MCP クライアントの トランスポートにはうまく対応しません。ダッシュボードからすでにアップロードされた メディアを参照するには、list_media を利用できます。この機能が必要な場合は、ぜひ貢献してください。

開発

npm install
npm run typecheck   # tsc --noEmit
npm test             # vitest — all tests run against a mocked fetch, no live API calls
npm run build        # emits dist/

テストスイートでは、すべてのリクエストにおける Authorization: Bearer ヘッダー、各ツールの正確なメソッド／URL／ボディのマッピング、401／403／429／500 のレスポンスに対するエラーコードのマッピング、および環境変数が設定されていない場合に即座に失敗する処理を網羅しています。このリポジトリのテストで実際のネットワーク呼び出しが行われることはありません。

ライセンス

MIT — LICENSE をご覧ください。