alttext-mcp

# AltText.ai MCP Server

An [MCP](https://modelcontextprotocol.io/) server that lets AI assistants generate alt text, manage image libraries, and queue alt text generation for web page images using the [AltText.ai](https://alttext.ai) API.

Works with Claude Desktop, Claude Code, Cursor, Windsurf, and any MCP-compatible client.

## Verify this package

This server runs `npx -y @alttext_ai/alttext-mcp`, which downloads and executes code with your API key in its environment. That's worth a moment of verification before you install — by you or by an AI agent doing the setup. Everything below should match:

| Signal | Value |
|--------|-------|
| npm package | [`@alttext_ai/alttext-mcp`](https://www.npmjs.com/package/@alttext_ai/alttext-mcp) |
| Source repository | [`github.com/alttextai/alttext-mcp`](https://github.com/alttextai/alttext-mcp) |
| Publisher | AltText.ai |
| Provenance | Published from this repo's CI with [npm provenance](https://docs.npmjs.com/generating-provenance-statements) — npm shows a verified build badge linking the package to this exact commit |

**The npm scope is `@alttext_ai` (with an underscore), while the GitHub org is `alttextai` (no underscore).** This is intentional, not a typosquat: the `@alttextai` npm scope was already taken, so we publish under `@alttext_ai`. The two names refer to the same official AltText.ai package.

To cryptographically verify the published package was built by this repo's CI — not just trust the metadata — run:

```sh
npm audit signatures
```

from a project where the package is installed. This validates the registry signature **and** the npm provenance attestation, which links the tarball to a specific commit and GitHub Actions build. A counterfeit package can forge `repository.url` and other metadata, but it cannot forge the provenance attestation — so this is the check that actually matters.

(For a quick, weaker cross-reference of the *claimed* source you can run `npm view @alttext_ai/alttext-mcp repository.url`, but note that field is publisher-controlled metadata and proves nothing on its own.)

### Pinning a version

The setup snippet uses `npx -y @alttext_ai/alttext-mcp`, which always resolves to the latest published version and re-runs it on every launch. That keeps you current, but it also means a future release runs automatically without review. If you want a reproducible, audited install, pin a specific version:

```json
"args": ["-y", "@alttext_ai/alttext-mcp@1.0.5"]
```

Run `npm audit signatures` against the pinned version, and bump it deliberately when you're ready to take a new release.

## Setup

**Requirements:** Node.js 22+ and an [AltText.ai API key](https://alttext.ai/account/api)

Add the server to your MCP client configuration:

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

**Where to add this:**

| Client | Config file |
|--------|-------------|
| Claude Desktop | `claude_desktop_config.json` |
| Claude Code | `.mcp.json` in your project root |
| Cursor | MCP settings in the Cursor preferences |
| Windsurf | MCP settings in the Windsurf preferences |

## Tools

### Account Management
| Tool | Description |
|------|-------------|
| `get_account` | Check your credit balance, usage, and account settings. |
| `update_account` | Update account name, webhook URL, or notification email. |

### Generate Alt Text
| Tool | Description |
|------|-------------|
| `generate_alt_text` | Generate alt text for an image URL. Supports multilingual output, custom prompts, keywords, and character limits. Uses account credits. |
| `generate_alt_text_from_file` | Generate alt text from a local image file. Automatically base64-encodes and uploads. Uses account credits. |
| `translate_image` | Add alt text in a new language for an existing image (by asset_id). Uses account credits. |

### Manage Image Library
| Tool | Description |
|------|-------------|
| `list_images` | List images in your library with pagination. |
| `search_images` | Search your image library by alt text content. |
| `get_image` | Get details for a specific image by asset ID. |
| `update_image` | Update alt text, tags, or metadata for an image. |
| `delete_image` | Delete an image from your library. |

### Bulk Operations
| Tool | Description |
|------|-------------|
| `bulk_create` | Bulk generate alt text from a CSV file with image URLs and optional metadata. |
| `scrape_page` | Scan a web page, find images missing alt text, and queue generation. Results are async -- use `list_images` to check progress. |

## Effects and processing

This package uses stdio and runs on the machine launching the MCP client. Image and CSV paths refer to that machine; selected file contents are uploaded to AltText.ai.

Generation and translation use your account credits. Additional languages and image conversion can increase the total. Check `get_account` before paid work. Generation can overwrite existing alt text when requested; updates replace supplied fields and deletion removes the image from the library.

CSV imports and page scraping queue background processing. An accepted request does not mean generation has finished; inspect the image library and any configured completion notifications. Tool annotations describe effects for clients; they do not enforce confirmation.

## Example Prompts

Once configured, just ask your AI assistant:

### Account & Credits
- "How many credits do I have left?"
- "Update my webhook URL to https://example.com/webhook"

### Generate Alt Text
- "Generate alt text for https://example.com/photo.jpg"
- "Generate alt text for this image" (with local file)
- "Generate alt text in French and Spanish for this image"
- "Translate image abc123 to German"

### Manage Library
- "Search my images for 'product photo'"
- "List my images"
- "Get details for image abc123"
- "Update the alt text for asset abc123"
- "Delete image xyz789"

### Bulk Operations
- "Generate alt text for images missing it on https://example.com"
- "Process this CSV file of image URLs" (bulk_create)

## Environment Variables

| Variable | Required | Description |
|----------|----------|-------------|
| `ALTTEXT_API_KEY` | Yes | Your [AltText.ai API key](https://alttext.ai/account/api) |
| `ALTTEXT_API_BASE_URL` | No | Override the API base URL (default: `https://alttext.ai/api/v1`) |

## Development

```sh
npm install
npm run build
npm test
npm run lint
```

Tests use mocked `fetch` calls -- no API key or network access needed.

Hosted deployments must rate-limit `POST /register` at a trusted edge using the verified client address. The Node service deliberately ignores forwarded client-address headers because accepting them without an authenticated proxy boundary would let callers spoof the rate-limit identity.

The production container and required settings are documented in [docs/deployment.md](docs/deployment.md).

## License

MIT

## Registry publishing

`server.json` describes the stdio npm package. Its name matches `mcpName` in `package.json`; both versions must match the release being submitted. Publish and verify that exact npm version before running `mcp-publisher publish`. Registry acceptance and directory approval are separate from an npm release.