gucken-image-reader 1.1.2

MCP server for image reader using OpenAI vision API (gpt-4o-mini)

English | 한국어

---

English

gucken-image-reader is an MCP (Model Context Protocol) server that uses OpenAI's Vision API to generate descriptive text for images. It provides a single describe_image tool via stdio, enabling any MCP-compatible client (such as Claude or custom applications) to send an image file path and receive a detailed textual description in response.

Installation

Prerequisite: UV

If you don't have UV installed, follow these steps:

• macOS / Linux

  curl -LsSf https://astral.sh/uv/install.sh | sh
  

• Windows (PowerShell)

  powershell -ExecutionPolicy ByPass -Command "irm https://astral.sh/uv/install.ps1 | iex"
  

Configuration

In your working directory, create a .env file or export the environment variable directly:

OPENAI_API_KEY=your_openai_api_key_here

Integration with an MCP host

Add the following entry to your claude_desktop_config.json (or other MCP-compatible host configuration):

{
  "mcpServers": {
    "image-reader": {
      "command": "uvx",
      "args": ["gucken-image-reader"],
      "env": {
        "OPENAI_API_KEY": "your_openai_api_key_here"
      }
    }
  }
}

• command: uvx
• args: gucken-image-reader
• env: Ensure that OPENAI_API_KEY is set.

Usage

1. Complete the installation and configuration steps above.

2. Start or restart your MCP host (e.g., the Claude desktop app); it will launch the gucken-image-reader server over stdio.

3. Send an MCP request (JSON-RPC) calling the describe_image method with a local image file

4. Receive a JSON response containing the image description generated by the model.

License

MIT

---

한국어

gucken-image-reader은 OpenAI Vision API를 활용해 이미지에 대한 설명을 생성하는 MCP(Model Context Protocol) 서버입니다. describe_image 툴을 stdio 방식으로 사용해 이미지를 텍스트로 설명해줍니다

설치

UV 설치 (아직 설치하지 않으셨다면)

• macOS / Linux

  curl -LsSf https://astral.sh/uv/install.sh | sh
  

• Windows (PowerShell)

  powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"
  

설정

다음 내용을 담은 .env 파일을 작업 디렉터리에 생성하거나, 환경 변수를 직접 설정하세요:

OPENAI_API_KEY=your_openai_api_key_here

MCP 호스트 통합

claude_desktop_config.json(또는 다른 MCP 호환 호스트 설정)에 다음 항목을 추가하세요:

{
  "mcpServers": {
    "image-reader": {
      "command": "uvx",
      "args": [
        "gucken-image-reader"
      ],
      "env": {
        "OPENAI_API_KEY": "your_openai_api_key_here"
      }
    }
  }
}

• command: uvx
• args: 콘솔 스크립트 이름 gucken-image-reader
• env: OPENAI_API_KEY 설정 필수

사용 방법

1. 위 설치·설정 과정을 완료합니다.
2. MCP 호스트(예: Claude 앱)를 실행하거나 재시작하면 서버가 stdio로 구동됩니다.
3. describe_image 툴을 호출하며 로컬 이미지 파일 경로를 전송합니다:
4. 모델이 생성한 이미지 묘사 텍스트를 응답으로 받습니다.

라이선스

MIT