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

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.