tteg 0.4.2

Free stock image search CLI for agents.

tteg

Free stock image search CLI and MCP server for AI coding agents. No API keys, no setup.

uv tool install tteg && tteg "mountain sunset"

Returns image URLs from Unsplash — ready to drop into any LLM workflow.

Install

uv tool install tteg
# or: pip install tteg

Usage

tteg "mountain sunset"
tteg "hero banner" -n 8 --orientation landscape
tteg "office workspace" --width 1920 --height 1080
tteg save "saas team working" ./public/hero
tteg batch examples/landing-page-images.json

Output

{
  "query": "mountain sunset",
  "results": [
    {
      "id": 1,
      "title": "A colorful sunrise over Jamnik village",
      "image_url": "https://images.unsplash.com/photo-...",
      "thumb_url": "https://images.unsplash.com/photo-...&w=200"
    },
    {
      "id": 2,
      "title": "Brown mountains under orange sky",
      "image_url": "https://images.unsplash.com/photo-...",
      "thumb_url": "https://images.unsplash.com/photo-...&w=200"
    }
  ]
}

Options

Flag	Default	Description
-n, --count	5	Number of results (1–10)
--orientation	any	landscape, portrait, square, or any
--width	—	Target width in pixels
--height	—	Target height in pixels

Save Locally

tteg save "saas team working" ./public/hero
tteg save "workspace desk" ./public/images/hero.jpg --orientation landscape

tteg save searches, picks one result, downloads it locally, and prints JSON with the saved path.

Batch A Page

tteg batch examples/landing-page-images.json

Manifest format:

{
  "images": [
    {
      "query": "saas dashboard hero",
      "output": "./public/images/hero",
      "orientation": "landscape"
    },
    {
      "query": "startup team meeting in office",
      "output": "./public/images/team",
      "orientation": "landscape"
    }
  ]
}

Use this when the page needs a hero, team shot, founder photo, testimonial portrait, or menu shot in one pass.

Starter Kit Drop-In

If you maintain a Claude Code, Codex, or Cursor starter kit, use the copy-paste blocks in STARTER_KIT.md.

It includes:

• a CLAUDE.md snippet for real-photo frontend work
• an AGENTS.md snippet for Codex projects
• an MCP config block for tool access inside agent hosts

Why

Agents frequently need real images — hero banners, product shots, blog headers. The normal path (register for Unsplash, get an API key, handle rate limits) is too much friction for a mid-task agent call.

tteg abstracts all of that. One install, one command, clean JSON out.

MCP server

Use tteg directly from Claude Code, Cursor, or any MCP-compatible host from this repo:

{
  "mcpServers": {
    "tteg": {
      "command": "uvx",
      "args": ["--from", "git+https://github.com/kiluazen/tteg", "tteg-mcp"]
    }
  }
}

You can also install the package once and run tteg-mcp locally.

Exposes:

• search_images(query, count, orientation, width, height)
• save_image(url, output_path)
• search_and_save_image(query, output_path, index, orientation, width, height)
• batch_save_images(images)

No API key needed.

Links

• tteg.kushalsm.com — landing page
• PyPI — pip install tteg
• Free: 50 queries/day. No account needed.