alttext-mcp

AltText.ai MCP 服务

一个 MCP 服务，可通过 AltText.ai API 让 AI 助手生成替代文本、管理图片库，并为网页图片排队生成替代文本。

兼容 Claude Desktop、Claude Code、Cursor、Windsurf 及任何兼容 MCP 的客户端。

验证此软件包

此服务会运行 npx -y @alttext_ai/alttext-mcp，下载代码并在包含你的 API key 的环境中执行。安装前值得花点时间验证一下，无论是你自己验证，还是由负责设置的 AI Agent 验证。以下信息应当一致：

信号	值
npm 软件包	@alttext_ai/alttext-mcp
源代码仓库	github.com/alttextai/alttext-mcp
发布者	AltText.ai
来源证明	由此仓库的 CI 使用 npm provenance 发布——npm 会显示一个已验证的构建徽章，将软件包链接到此确切提交

npm 作用域是 @alttext_ai（带下划线），而 GitHub 组织是 alttextai（不带下划线）。 这是有意为之，并非仿冒：@alttextai npm 作用域已被占用，因此我们使用 @alttext_ai 发布。这两个名称指向同一个 AltText.ai 官方软件包。

若要通过密码学方式验证已发布的软件包确实由此仓库的 CI 构建（而非仅仅相信元数据），请在安装了该软件包的项目中运行：

npm audit signatures

这会验证注册表签名以及 npm 来源证明声明，该声明将压缩包链接到特定提交和 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 key

将此服务添加到 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 命令使用；该命令还可通过完整访问权限的 key 管理账户的网站 API keys。命令、标志和退出代码请参见 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

Agent 技能

skills/alttext 教 Claude Code、Codex 和其他编码 Agent 使用 alttext CLI：先检查 whoami，解析 --json，在执行轮换、撤销或删除前进行试运行并征求确认，不在对话中泄露令牌，以及处理经销商的入驻、账单和密钥泄露工作流。此技能不包含任何凭据，并会告知 Agent 让你自行运行 alttext login，而不是把密钥粘贴到聊天中。需要先安装 CLI。

使用 npx skills，适用于任何受支持的 Agent：

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	扫描网页，查找缺少替代文本的图片，并将其加入生成队列。结果为异步处理——使用 list_images 查看进度。

影响与处理

此软件包使用 stdio，并在启动 MCP 客户端的机器上运行。图片和 CSV 路径均指向该机器；选中的文件内容会上传到 AltText.ai。

生成和翻译会使用账户点数。增加语言或转换图片可能会提高总点数消耗。执行付费操作前，请使用 get_account 检查账户。按需生成时，可以覆盖现有替代文本；更新会替换所提供的字段，删除操作会将图片从图片库中移除。

CSV 导入和网页抓取会将任务加入后台处理队列。请求被接受并不意味着生成已完成；请检查图片库和已配置的完成通知。工具注释会向客户端说明操作影响，但不会强制要求确认。

示例提示词

配置完成后，只需向你的 AI 助手提出要求：

账户与点数

• “我还剩多少点数？”
• “将我的 webhook URL 更新为 https://example.com/webhook”

生成替代文本

• “为 https://example.com/photo.jpg 生成替代文本”
• “为这张图片生成替代文本”（使用本地文件）
• “为这张图片生成法语和西班牙语的替代文本”
• “将图片 abc123 翻译成德语”

管理图片库

• “搜索替代文本中包含‘product photo’的图片”
• “列出我的图片”
• “获取图片 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 会检查每个技能的 frontmatter 和链接，并验证技能中提及的每个 alttext 命令和标志都存在于构建后的 CLI 中。该命令会在构建完成后作为 npm run check 的一部分运行。

托管部署必须在可信边缘对 POST /register 进行速率限制，并使用已验证的客户端地址。Node 服务会刻意忽略转发的客户端地址标头，因为若没有经过身份验证的代理边界就接受这些标头，调用方就能伪造速率限制所依据的身份。

生产容器和必需设置详见 docs/deployment.md。

许可证

MIT

Registry 发布

server.json 描述了 stdio npm 软件包。其名称与 packages/mcp/package.json 中的 mcpName 相匹配；两个版本都必须与待提交的版本一致。运行 mcp-publisher publish 前，请先发布并验证对应的 npm 版本。Registry 接受和目录审批与 npm 发布是彼此独立的。