# tensorart-mcp

An [MCP](https://modelcontextprotocol.io) server for the **Tensor.Art TAMS API**. It lets Claude (Claude Code,
Claude Desktop, Cursor, any MCP client) generate images on Tensor.Art with any public checkpoint or your own
**private LoRA**, run img2img and ComfyUI workflows, and estimate credits before spending them.

Unofficial project, not affiliated with Tensor.Art. It only uses the official, documented API
([TAMS docs](https://tams-docs.tusiart.com/docs/api/intro)): no scraping of the website.

## Before you start: TAMS is billed on its own

TAMS credits are separate from the tensor.art website subscription (Pro/Premium credits **cannot** be used through
the API). TAMS gives 1,000 free credits on first login, then credits are prepaid (about $0.003 each; a 30-step image
is usually 1–2 credits). Use `estimate_credits` to check before generating.

## Setup

1. Sign in at [tams.tensor.art](https://tams.tensor.art) and create an app. Note its **endpoint** and either an
   **API key** (Bearer) or the **app id** plus an RSA key pair:
   ```bash
   openssl genrsa -out private_key.pem 2048
   openssl rsa -in private_key.pem -pubout -out public_key.pem   # paste public_key.pem in the app settings
   ```
2. Install:
   ```bash
   git clone https://github.com/giacomodiguida/tensorart-mcp && cd tensorart-mcp
   uv venv && uv pip install -e .
   ```
3. Add it to your MCP client. Claude Code:
   ```bash
   claude mcp add tensorart --env TAMS_ENDPOINT=https://<your-app-endpoint> --env TAMS_API_KEY=<key> \
     -- /path/to/tensorart-mcp/.venv/bin/tensorart-mcp
   ```
   Claude Desktop (`claude_desktop_config.json`):
   ```json
   {"mcpServers": {"tensorart": {
     "command": "/path/to/tensorart-mcp/.venv/bin/tensorart-mcp",
     "env": {"TAMS_ENDPOINT": "https://<your-app-endpoint>", "TAMS_APP_ID": "<app id>",
             "TAMS_PRIVATE_KEY_PATH": "/path/to/private_key.pem"}}}}
   ```

| Variable | Meaning |
|---|---|
| `TAMS_ENDPOINT` | your app endpoint (default `https://ap-east-1.tensorart.cloud`) |
| `TAMS_API_KEY` | Bearer key (simple auth) |
| `TAMS_API_KEY_FILE` | path to a file containing the key (keeps it out of your MCP config) |
| `TAMS_APP_ID` + `TAMS_PRIVATE_KEY_PATH` | signed requests (TAMS-SHA256-RSA) instead of the key |
| `TAMS_OUTPUT_DIR` | where images are saved (default `~/Pictures/tensorart`) |
| `TAMS_DEFAULT_MODEL` | checkpoint id used when a call has no `model_id` |

## Tools

| Tool | What it does |
|---|---|
| `generate_image` | text-to-image; checkpoint + LoRAs (with `access_key` for private ones); waits and saves files |
| `estimate_credits` | cost of a text-to-image job without running it |
| `image_to_image` | uploads a local image and re-renders it |
| `run_workflow` | ComfyUI-style node map (`classType` / `inputs`) |
| `run_workflow_template` | a saved Tensor.Art workflow template with field values |
| `get_job` / `cancel_job` | status, images, cancel |
| `get_model` | info on a checkpoint or LoRA id |
| `upload_image` | upload a file, get a resource id |

**Model ids** are the numbers in a model page URL (`tensor.art/models/<id>`). For a **private** model, copy the
`accessKey` from its page and pass it (`model_access_key`, or `access_key` inside a LoRA item).

Example prompt for Claude: *"Generate with tensorart: checkpoint 123…, LoRA 456… weight 1.0 access key …,
30 steps, CFG 4, 832×1216, prompt 'ohwx woman, mirror selfie…'"*.

## Development

```bash
uv pip install -e ".[dev]" && .venv/bin/python -m pytest -q
```

MIT license.