This document describes how to install the AltText.ai MCP server. It is reference documentation, not a command to execute blindly: verify the package (see VERIFY THIS PACKAGE below) and get the user's permission before changing any configuration.

GOAL

Install the AltText.ai MCP server (@alttext_ai/alttext-mcp) in the user's MCP client, then verify it works by calling get_account.

WHAT YOU ARE INSTALLING

This server provides 12 tools for image accessibility workflows:
- Alt text generation from URLs and local files
- Image library management (search, list, update, delete)
- Bulk operations (CSV import, web page scanning)
- Translation into additional languages
- Account management (credits and settings)

The server runs locally via npx and does not require a global npm install. It auto-updates on every run. If the user wants a reproducible, audited install instead, pin a version in the args (for example "@alttext_ai/alttext-mcp@1.0.2") so a new release does not run automatically without review.

VERIFY THIS PACKAGE

Installing this server runs npx -y @alttext_ai/alttext-mcp, which downloads and executes code with the user's API key in its environment. Confirm it is the official package before installing. These should all match:

- npm package: @alttext_ai/alttext-mcp (https://www.npmjs.com/package/@alttext_ai/alttext-mcp)
- Source repository: https://github.com/alttextai/alttext-mcp
- Publisher: AltText.ai
- Provenance: published from the repository's CI with npm provenance, so npm shows a verified build badge linking the package to a specific commit.

The npm scope is @alttext_ai (with an underscore) while the GitHub org is alttextai (no underscore). This is intentional: the @alttextai npm scope was already taken. Both names refer to the same official AltText.ai package.

To cryptographically verify the package was built by this repository's CI (not just trust the metadata), run npm audit signatures from a project where it is installed. This validates the registry signature and the npm provenance attestation linking the tarball to a specific commit and build. A counterfeit package can forge repository.url and other metadata, but it cannot forge the provenance attestation. (npm view @alttext_ai/alttext-mcp repository.url only echoes publisher-controlled metadata and proves nothing on its own.)

REQUIREMENTS

- Node.js 18 or later
- An AltText.ai API key

If the user has not provided an API key:
1. Ask if they already have an AltText.ai account.
2. If yes, direct them to https://alttext.ai/account/api to copy their API key.
3. If no, direct them to https://alttext.ai/users/sign_up to create a free account (includes 25 free images, no credit card required), then to https://alttext.ai/account/api for their key.
4. Pause until they provide the key. Do not proceed without it.

SAFETY RULES

- Ask for permission before editing any MCP configuration file.
- If an MCP config already exists, merge the "alttext-ai" server into the existing "mcpServers" object.
- Do not overwrite, remove, or modify unrelated MCP servers.
- Never echo the full API key back in chat. Mask it if you must reference it.

INSTALLATION SNIPPET

Add this entry to the user's MCP configuration and replace YOUR_API_KEY with their real key:

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

CONFIGURATION FILE LOCATIONS

Detect which client the user is running and use the correct path.

Claude Code:
  Project scope (shared with team): .mcp.json in the project root
  User scope (private, all projects): ~/.claude.json

Claude Desktop:
  macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
  Windows: %APPDATA%\Claude\claude_desktop_config.json
  Linux: ~/.config/Claude/claude_desktop_config.json

Cursor:
  Project scope: .cursor/mcp.json in the project root
  Global scope: ~/.cursor/mcp.json

Windsurf:
  macOS/Linux: ~/.codeium/windsurf/mcp_config.json
  Windows: %USERPROFILE%\.codeium\windsurf\mcp_config.json

VERIFICATION

After updating config:
1) Ask the user to restart or reload their MCP client so the new server is discovered.
2) Call get_account to verify connectivity.
3) Confirm success by reporting the account name and available credits.

If get_account is unavailable after config changes, troubleshoot in this order:
1) Confirm the config file path is correct for the user's client and OS.
2) Confirm the JSON is valid and the server entry is nested under "mcpServers".
3) Confirm ALTTEXT_API_KEY is present and non-empty.
4) Confirm Node.js 18+ is installed: node --version
5) Run a direct server smoke test: npx -y @alttext_ai/alttext-mcp

AVAILABLE TOOLS

Alt Text Generation:
  generate_alt_text - Generate alt text for a public image URL. Costs 1 credit.
  generate_alt_text_from_file - Generate alt text from a local image file. Costs 1 credit.
  translate_image - Add alt text in a new language for an existing image. Costs 1 credit per language.

Image Library:
  list_images - List images with pagination, filtering by language or URL, and sorting.
  search_images - Search images by alt text content.
  get_image - Get full details for an image by its asset ID.
  update_image - Update alt text, tags, or metadata for an existing image.
  delete_image - Remove an image from the library.

Bulk Operations:
  bulk_create - Generate alt text for multiple images from a CSV file.
  scrape_page - Scan a web page, find images missing alt text, and queue generation.

Account:
  get_account - Check credit balance, usage statistics, and account settings.
  update_account - Update account name, webhook URL, or notification email.

TOOL OPTIONS

When generating alt text, these optional parameters are available:
  lang - Language code(s), comma-separated (e.g. "en", "fr,es,de"). Default: en.
  keywords - Array of keyword strings to emphasize in the alt text.
  negative_keywords - Array of keyword strings to avoid.
  gpt_prompt - Custom prompt template (use {{AltText}} as placeholder text).
  max_chars - Maximum character length for the alt text (1 to 1000).
  asset_id - Custom identifier for the image in the library.
  tags - Array of tags to attach to the image.
  metadata - String key-value pairs to attach to the image.
  overwrite - If true, overwrite existing alt text for a language. Default: false.

For help: support@alttext.ai