tf-tools-mcp 0.1.2

Image generation and understanding tools using OpenRouter and Zhipu AI

TF Tools MCP

Image generation and understanding tools for MCP (Model Context Protocol) using OpenRouter and Zhipu AI.

Features

• Text-to-Image Generation: Generate images from text prompts using multiple models via OpenRouter

  • Supported models: Gemini 2.0 Flash, Seedream 4.5, GPT-5 Image, FLUX.2 Max/Pro
  • Optional AI-powered prompt enhancement using GLM-4.6V
  • Multiple quality levels and layouts

• Image-to-Image Generation: Transform reference images with text guidance

  • Support for local files and URLs
  • Smart prompt enhancement for various transformation modes

• Image Understanding: Analyze images with GLM-4.6V vision model

  • Single and batch image analysis
  • Multiple analysis templates: description, OCR, object detection, chart analysis
  • Detailed token usage statistics

Installation

Using uv (recommended)

# Clone the repository
git clone https://github.com/turingfocus/tf_tools_mcp.git
cd tf_tools_mcp

# Install dependencies
uv sync

# Install the package in development mode
uv pip install -e .

Using pip

# Clone the repository
git clone https://github.com/turingfocus/tf_tools_mcp.git
cd tf_tools_mcp

# Install dependencies
pip install -e .

Configuration

1. Copy .env.example to .env:

cp .env.example .env

2. Edit .env and add your API keys:

# Required for image generation
OPENROUTER_API_KEY=your_openrouter_api_key_here

# Required for image understanding
ZHIPUAI_API_KEY=your_zhipuai_api_key_here

# Optional settings
IMAGE_STORAGE_DIR=./generated_images
ENABLE_PROMPT_ENHANCEMENT=true

Getting API Keys

• OpenRouter API Key: Sign up at https://openrouter.ai/ and get your key from https://openrouter.ai/keys
• ZhipuAI API Key: Sign up at https://open.bigmodel.cn/ and get your key from https://open.bigmodel.cn/usercenter/apikeys

Usage with MCP Clients

Claude Desktop

Add the server to your Claude Desktop configuration:

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

{
  "mcpServers": {
    "tf-tools-mcp": {
      "command": "uv",
      "args": [
        "--directory",
        "/path/to/tf_tools_mcp",
        "run",
        "tf-tools-mcp"
      ],
      "env": {
        "OPENROUTER_API_KEY": "your_api_key_here",
        "ZHIPUAI_API_KEY": "your_api_key_here"
      }
    }
  }
}

Or if installed with pip:

{
  "mcpServers": {
    "tf-tools-mcp": {
      "command": "tf-tools-mcp",
      "env": {
        "OPENROUTER_API_KEY": "your_api_key_here",
        "ZHIPUAI_API_KEY": "your_api_key_here"
      }
    }
  }
}

Restart Claude Desktop and the tools will be available.

Claude Code (CLI)

Install as an MCP server:

claude mcp install tf-tools-mcp

Or configure manually in ~/.config/claude-code/mcp_config.json:

{
  "mcpServers": {
    "tf-tools-mcp": {
      "command": "tf-tools-mcp",
      "env": {
        "OPENROUTER_API_KEY": "your_api_key_here",
        "ZHIPUAI_API_KEY": "your_api_key_here"
      }
    }
  }
}

Available Tools

text_to_image

Generate images from text prompts.

Parameters:

• prompt (string, required): Text prompt for image generation
• model (string, required): OpenRouter model ID
  • google/gemini-2.0-flash-exp-image-generation
  • bytedance-seed/seedream-4.5
  • openai/gpt-image-1
  • openai/gpt-image-1-mini
  • black-forest-labs/flux-2-max
  • black-forest-labs/flux-2-pro
• mode (string, optional): Prompt enhancement mode
  • technical_architecture: For technical diagrams
  • design_mockup: For UI/UX designs
  • promotional_material: For marketing content
  • office_chart: For business charts
  • custom: No enhancement (default)
• quality (string, optional): Image quality (low, medium, high) - default: medium
• layout (string, optional): Image layout (square, landscape, portrait) - default: square
• filename_prefix (string, optional): Prefix for saved filename - default: generated

Example:

Generate an image of a sunset over mountains with vibrant colors
using the Gemini 2.0 Flash model, high quality, landscape layout.

image_to_image

Generate images from reference images with text guidance.

Parameters:

• prompt (string, required): Text prompt for image generation
• reference_image (string, required): Path to reference image (local file or URL)
• model (string, required): OpenRouter model ID (same as text_to_image)
• mode (string, optional): Prompt enhancement mode
  • content_adjustment: Adjust content while keeping style
  • element_replace: Replace specific elements
  • style_transfer: Transfer artistic style
  • text_modification: Modify text in image
  • custom: No enhancement (default)
• quality, layout, filename_prefix: Same as text_to_image

Example:

Transform this image to have a cyberpunk aesthetic
using the reference image at /path/to/image.jpg
with the FLUX.2 Max model.

image_understanding

Analyze and understand images using GLM-4.6V.

Parameters:

• images (array of strings, required): List of image paths or URLs
• prompt_template (string, optional): Analysis template
  • describe: General image description (default)
  • ocr: Text extraction (OCR)
  • detect_objects: Object detection
  • analyze_chart: Chart/data visualization analysis
  • custom: Use custom prompt
• custom_prompt (string, optional): Custom prompt (required when prompt_template is custom)
• model (string, optional): GLM model to use
  • glm-4.6v: High performance
  • glm-4.6v-flashx: Fast (default)

Example:

Analyze this image /path/to/image.jpg
and describe all the objects you can see.

Development

Running Tests

# Run all tests
make test

# Run with real API calls (requires API keys)
make test-real

Project Structure

tf_tools_mcp/
├── tf_tools_mcp/
│   ├── server.py              # MCP server entry point
│   ├── tools/
│   │   ├── img_gen_tools/     # Image generation tools
│   │   │   ├── text_to_image.py
│   │   │   ├── image_to_image.py
│   │   │   ├── constants.py   # Model configurations
│   │   │   ├── types.py       # Type definitions
│   │   │   └── enhancers/     # Prompt enhancement
│   │   └── file_preview_tools/
│   │       └── image_understanding.py
│   └── __init__.py
├── tests/                     # Test suite
├── pyproject.toml            # Project configuration
├── Makefile                  # Build scripts
└── README.md

License

MIT License - see LICENSE file for details

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

Support

For issues and questions, please use the GitHub issue tracker.