Read Image MCP Server v1.0.0

MCP (Model Context Protocol) server dùng Google Gemini để đọc và mô tả nội dung ảnh. Hỗ trợ cả ảnh đơn và nhiều ảnh cùng lúc (so sánh, đối chiếu).

🚀 Tính năng

• 📷 Đọc ảnh đơn — Gửi 1 ảnh và nhận mô tả chi tiết bằng tiếng Việt
• 🖼️ Đọc nhiều ảnh — Gửi nhiều ảnh trong 1 lần gọi để so sánh, đối chiếu
• 📝 Prompt tùy chỉnh — Đặt câu hỏi cụ thể về ảnh (không bắt buộc)
• 🎨 Hỗ trợ nhiều định dạng — PNG, JPEG, GIF, WebP, BMP, SVG, TIFF, ICO, AVIF
• ⚡ Tích hợp MCP — Dùng được ngay trong Claude Code, VS Code, JetBrains...

📋 Yêu cầu

• Node.js >= 18
• Google AI Studio API Key (miễn phí)
• Claude Code hoặc MCP client khác

🔧 Cài đặt

1. Clone repo

git clone https://github.com/hovie/read-image-mcp.git
cd read-image-mcp

2. Cài đặt dependencies

npm install

3. Build

npm run build

⚙️ Cấu hình

Lấy Gemini API Key (miễn phí)

1. Truy cập Google AI Studio
2. Đăng nhập bằng tài khoản Google
3. Nhấn "Create API Key" để tạo key mới
4. Copy key vừa tạo

Cấu hình MCP Server

Có 2 cách cấu hình:

Cách 1: Dùng file .mcp.json (khuyên dùng cho Claude Code)

Copy file mẫu và sửa API key:

copy .mcp.json.example .mcp.json

Sau đó mở .mcp.json và thay YOUR_GEMINI_API_KEY_HERE bằng API key thật của bạn:

{
  "mcpServers": {
    "read-image": {
      "command": "npx",
      "args": ["tsx", "d:\\MCP\\read-image\\src\\index.ts"],
      "env": {
        "GEMINI_API_KEY": "AIzaSy...your-key-here",
        "GEMINI_MODEL": "gemini-2.5-flash"
      }
    }
  }
}

Cách 2: Dùng file .env

copy .env.example .env

Sửa .env với API key của bạn:

GEMINI_API_KEY=your-api-key-here
GEMINI_MODEL=gemini-2.5-flash

Chọn Model

Model	Mô tả	Dùng khi
gemini-2.5-flash	Nhanh, miễn phí	Hầu hết trường hợp
gemini-2.5-pro	Mạnh hơn, có trả phí	Ảnh phức tạp, cần phân tích sâu

Sửa biến GEMINI_MODEL trong .env hoặc .mcp.json để đổi model.

🏃 Cách chạy

Chạy dev (không cần build)

npm run dev

Chạy production (sau khi build)

npm run build
npm start

Dùng trong Claude Code

Sau khi cấu hình .mcp.json, Claude Code sẽ tự động nhận MCP server. Bạn có thể gọi tool read_image từ Claude Code để đọc ảnh.

Tool sẽ xuất hiện với tên read_image với các tham số:

Tham số	Loại	Bắt buộc	Mô tả
image_path	string	Không*	Đường dẫn đến 1 file ảnh
image_paths	string[]	Không*	Đường dẫn đến nhiều file ảnh
prompt	string	Không	Câu hỏi / yêu cầu về ảnh

*Phải có ít nhất 1 trong 2: image_path hoặc image_paths

📖 Ví dụ

Đọc 1 ảnh

Dùng read_image đọc ảnh D:\photos\cat.png

Đọc nhiều ảnh để so sánh

Dùng read_image đọc 2 ảnh D:\photos\before.png và D:\photos\after.png,
so sánh sự khác biệt giữa 2 ảnh

Hỏi câu hỏi cụ thể về ảnh

Dùng read_image đọc ảnh D:\screenshots\dashboard.png,
cho biết có những số liệu gì trên dashboard này?

📁 Cấu trúc project

read-image-mcp/
├── src/
│   └── index.ts          # MCP server chính
├── dist/                  # Build output (sau khi chạy npm run build)
├── .env.example           # Mẫu file biến môi trường
├── .mcp.json.example      # Mẫu cấu hình MCP cho Claude Code
├── .gitignore
├── package.json
├── tsconfig.json
└── README.md

🔒 Bảo mật

• KHÔNG commit file .env hoặc .mcp.json chứa API key thật
• File .env và .mcp.json đã được thêm vào .gitignore
• Dùng file .example làm mẫu cho người khác
• Nếu lỡ commit API key, xóa ngay trên Google AI Studio và tạo key mới

🛠️ Tech Stack

• Model Context Protocol SDK — Giao thức MCP
• Google Generative AI SDK — Gemini API
• TypeScript + tsx — Runtime

📄 License

MIT