alttext-mcp

AltText.ai MCP サーバー

AI アシスタントが AltText.ai API を使用して代替テキストを生成し、画像ライブラリを管理し、ウェブページ上の画像の代替テキスト生成をキューに登録できる MCP サーバーです。

Claude Desktop、Claude Code、Cursor、Windsurf、および MCP 互換のあらゆるクライアントで動作します。

このパッケージを検証する

このサーバーは npx -y @alttext_ai/alttext-mcp を実行します。このコマンドは、環境内に API キーがある状態でコードをダウンロードして実行します。インストールする前に、少し時間を取って検証する価値があります。ご自身で行う場合も、セットアップを行う AI エージェントに任せる場合も同様です。以下の内容がすべて一致しているはずです。

シグナル	値
npm パッケージ	@alttext_ai/alttext-mcp
ソースリポジトリ	github.com/alttextai/alttext-mcp
公開元	AltText.ai
来歴	npm provenance を使用し、このリポジトリの CI から公開されています。npm には、パッケージをこの特定のコミットに紐付ける検証済みビルドバッジが表示されます

npm スコープは @alttext_ai（アンダースコアあり）で、GitHub 組織は alttextai（アンダースコアなし）です。 これは意図的なものであり、タイポスクワットではありません。@alttextai npm スコープはすでに使用されていたため、@alttext_ai で公開しています。この2つの名前は、同じ公式 AltText.ai パッケージを指しています。

公開されたパッケージが単にメタデータを信頼するだけでなく、このリポジトリの CI によってビルドされたことを暗号学的に検証するには、パッケージがインストールされているプロジェクトで次を実行します。

npm audit signatures

これにより、レジストリの署名とnpm の来歴証明の両方が検証されます。来歴証明は、tarball を特定のコミットと GitHub Actions のビルドに紐付けます。偽造パッケージは repository.url などのメタデータを偽装できますが、来歴証明は偽造できません。そのため、実際に重要なのはこの検証です。

（ソースとして申告されている内容を手早く確認するだけなら、npm view @alttext_ai/alttext-mcp repository.url を実行できます。ただし、このフィールドは公開元が管理するメタデータであり、それ単独では何も証明しない点に注意してください。）

バージョンの固定

セットアップのスニペットでは npx -y @alttext_ai/alttext-mcp を使用しています。このコマンドは常に最新の公開バージョンを解決し、起動するたびに再実行します。常に最新の状態を保てますが、将来のリリースがレビューなしで自動的に実行されることも意味します。再現可能で監査済みのインストールを希望する場合は、特定のバージョンを固定してください。

"args": ["-y", "@alttext_ai/[email protected]"]

固定したバージョンに対して npm audit signatures を実行し、新しいリリースを導入する準備ができたら、意図的にバージョンを更新してください。

セットアップ

要件： Node.js 22 以降、および AltText.ai API キー

MCP クライアントの設定にサーバーを追加します。

{
  "mcpServers": {
    "alttext-ai": {
      "command": "npx",
      "args": ["-y", "@alttext_ai/alttext-mcp"],
      "env": {
        "ALTTEXT_API_KEY": "your-api-key"
      }
    }
  }
}

追加先：

クライアント	設定ファイル
Claude Desktop	claude_desktop_config.json
Claude Code	プロジェクトルートの .mcp.json
Cursor	Cursor の環境設定にある MCP 設定
Windsurf	Windsurf の環境設定にある MCP 設定

コマンドラインツール

同じ操作を alttext コマンドでも実行できます。また、フルアクセスキーを使ってアカウントのサイト API キーを管理することもできます。コマンド、フラグ、終了コードについては、packages/cli/README.md を参照してください。

@alttext_ai/cli が npm でリリースされた後は、次のようにします。

npm install -g @alttext_ai/cli
alttext login
alttext whoami

それまでは、このリポジトリをクローンしてビルドしてください。

npm install
npm run build
npm link --workspace packages/cli

エージェントスキル

skills/alttext は、Claude Code、Codex、その他のコーディングエージェントに、alttext CLI の操作方法を教えます。最初に whoami を確認すること、--json を解析すること、ローテーション、取り消し、削除の前にドライランを実行して確認を求めること、トークンを会話に含めないこと、そして販売代理店向けのオンボーディング、請求、漏えいしたキーへの対応ワークフローが含まれます。このスキルに認証情報は含まれておらず、キーをチャットに貼り付けるのではなく、自分で alttext login を実行するようエージェントに指示します。CLI のインストールが必要です。

npx skills を使う場合、サポートされているエージェントであれば次のように実行します。

npx skills add alttextai/alttext-mcp --skill alttext

Claude Code プラグインとして、このリポジトリのプラグインマーケットプレイスから追加します。

claude plugin marketplace add alttextai/alttext-mcp
claude plugin install alttext@alttext-ai

または、Claude Code セッション内で次のコマンドを実行して、一度に追加します（2.1.275 以降）：/plugin install alttext --marketplace alttextai/alttext-mcp。

ローカルクローンから追加する場合は、代わりにクローンのパスを指定します：npx skills add ./alttext-mcp --skill alttext、または claude plugin marketplace add ./alttext-mcp。

ツール

アカウント管理

ツール	説明
get_account	クレジット残高、使用状況、アカウント設定を確認します。
update_account	アカウント名、Webhook URL、通知用メールアドレスを更新します。

代替テキストの生成

ツール	説明
generate_alt_text	画像 URL から代替テキストを生成します。多言語出力、カスタムプロンプト、キーワード、文字数制限に対応しています。アカウントのクレジットを使用します。
generate_alt_text_from_file	ローカルの画像ファイルから代替テキストを生成します。自動的に Base64 エンコードしてアップロードします。アカウントのクレジットを使用します。
translate_image	既存の画像（asset_id で指定）に新しい言語の代替テキストを追加します。アカウントのクレジットを使用します。

画像ライブラリの管理

ツール	説明
list_images	ライブラリ内の画像をページネーション付きで一覧表示します。
search_images	代替テキストの内容で画像ライブラリを検索します。
get_image	指定した画像の詳細をアセット ID で取得します。
update_image	画像の代替テキスト、タグ、メタデータを更新します。
delete_image	ライブラリから画像を削除します。

一括操作

ツール	説明
bulk_create	画像 URL と任意のメタデータを含む CSV ファイルから、代替テキストを一括生成します。
scrape_page	Web ページをスキャンし、代替テキストがない画像を見つけて生成キューに追加します。結果は非同期で処理されます。進行状況は list_images で確認してください。

影響と処理

このパッケージは stdio を使用し、MCP クライアントを起動したマシン上で実行されます。画像と CSV のパスはそのマシン上のものを参照します。選択したファイルの内容は AltText.ai にアップロードされます。

生成と翻訳にはアカウントのクレジットを使用します。追加の言語や画像変換によって、合計使用量が増える場合があります。有料の処理を行う前に get_account で確認してください。生成時に指定すると、既存の代替テキストが上書きされることがあります。更新では指定したフィールドが置き換えられ、削除すると画像はライブラリから取り除かれます。

CSV のインポートとページのスクレイピングでは、バックグラウンド処理がキューに追加されます。リクエストが受け付けられても、生成が完了したことを意味するわけではありません。画像ライブラリと、設定済みの完了通知を確認してください。ツールのアノテーションはクライアントに処理の影響を説明するものであり、確認を強制するものではありません。

プロンプトの例

設定が完了したら、AI アシスタントに次のように尋ねるだけです。

アカウントとクレジット

• 「残りのクレジットはいくつですか？」
• 「Webhook URL を https://example.com/webhook に更新してください」

代替テキストの生成

• 「https://example.com/photo.jpg の代替テキストを生成してください」
• 「この画像の代替テキストを生成してください」（ローカルファイルを使用）
• 「この画像の代替テキストをフランス語とスペイン語で生成してください」
• 「画像 abc123 をドイツ語に翻訳してください」

ライブラリの管理

• 「画像から『商品写真』を検索してください」
• 「画像を一覧表示してください」
• 「画像 abc123 の詳細を取得してください」
• 「アセット abc123 の代替テキストを更新してください」
• 「画像 xyz789 を削除してください」

一括操作

• 「https://example.com で代替テキストがない画像の代替テキストを生成してください」
• 「この画像 URL の CSV ファイルを処理してください」（bulk_create）

環境変数

変数	必須	説明
ALTTEXT_API_KEY	はい	お使いのAltText.ai API キー
ALTTEXT_API_BASE_URL	いいえ	API のベース URL を上書きします（デフォルト：https://alttext.ai/api/v1）

開発

このリポジトリは npm ワークスペースです。packages/core（プライベート API クライアント、スキーマ、フォーマッター。公開される各パッケージにバンドルされます）、packages/mcp（@alttext_ai/alttext-mcp）、packages/cli（@alttext_ai/cli、alttext コマンド）で構成されています。

npm install
npm run check

編集するのはルートの package.json のバージョンのみです。npm run version:stamp を実行すると、その値が各パッケージと server.json にコピーされます。値にずれがあると CI は失敗します。このバージョンに一致する v* タグを付けると、両方のパッケージが公開されます。

テストでは fetch の呼び出しをモックするため、API キーもネットワークアクセスも必要ありません。

npm run skills:validate は各スキルのフロントマターとリンクに加え、スキルで使用されているすべての alttext コマンドとフラグがビルド済み CLI に存在することを確認します。ビルド後、npm run check の一部として実行されます。

ホスト型のデプロイでは、検証済みのクライアントアドレスを使用して、信頼できるエッジで POST /register にレート制限を設定する必要があります。認証済みのプロキシ境界なしで転送されたクライアントアドレスヘッダーを受け入れると、呼び出し元がレート制限の識別情報を偽装できるため、Node サービスではこれらのヘッダーを意図的に無視します。

本番用コンテナーと必須の設定については、docs/deployment.md を参照してください。

ライセンス

MIT

レジストリへの公開

server.json は stdio npm パッケージを記述します。その名前は packages/mcp/package.json の mcpName と一致し、両方のバージョンは申請するリリースと一致している必要があります。正確な npm バージョンを公開して検証してから、mcp-publisher publish を実行してください。レジストリでの受け入れとディレクトリでの承認は、npm のリリースとは別の手続きです。