Artguru MCP

Artguru MCP is a Python MCP server for the Artguru Open API Platform. It wraps Artguru image APIs and exposes them as MCP tools for clients such as Codex, Claude Desktop, and other MCP-compatible agents.

中文版本请见 README.zh-CN.md.

Requirements

• Python 3.11 or later.
• An Artguru API key.

Installation

Install the package from PyPI:

pip install artguru-mcp

MCP client configuration

Add the server to your MCP client configuration:

{
  "mcpServers": {
    "artguru-mcp": {
      "command": "artguru-mcp",
      "env": {
        "ARTGURU_API_KEY": "your_api_key"
      }
    }
  }
}

You can also pass api_key directly to each tool. Using ARTGURU_API_KEY is recommended because it keeps secrets out of prompts and tool arguments.

Tools

• artguru_get_credits: Get total, used, and remaining account credits.
• artguru_upload_image: Upload a local image and return an Artguru image URL.
• artguru_photo_enhance: Start a photo enhancement task from an image URL.
• artguru_image_to_image: Start an image-to-image generation task.
• artguru_get_task_status: Check a task by business type and task ID.
• artguru_photo_enhance_with_progress: Upload a local image, create an enhancement task, poll status, and return every step in steps.
• artguru_image_to_image_with_progress: Upload a local image, create an image-to-image task, poll status, and return every step in steps.

Use the _with_progress tools when you want the client to show the full workflow. Their response includes step events such as upload_started, upload_succeeded, task_create_started, task_create_succeeded, poll_started, poll_attempt, poll_succeeded, poll_failed, and poll_timeout.

If upload, task creation, or polling fails, the tool returns status: "FAILED" with a failure event and an error message. If polling does not finish within max_poll_attempts, the tool returns status: "TIMEOUT".

Environment variables

• ARTGURU_API_KEY: Required Artguru API key.
• ARTGURU_BASE_URL: Optional API base URL. Defaults to https://api.artguru.ai/.

Development

Install development dependencies and run checks with uv:

uv run --extra dev python -m pytest
uv run --extra dev ruff check .
uv build

Project links

• Documentation: https://x6oynfyxq3.apifox.cn/authentication-7269269m0