Aesthetic MCP

审美评分器MCP服务器

MCP（模型上下文协议）服务器，使用 rsinema/审美评分 Hugging Face的模特。

特性

• 7美学维度：跨多个质量指标分析图像

- 总体美学评分——总体视觉吸引力 - 技术质量-图像清晰度、噪声、伪影 - 构图——三分法、平衡、框架 - 照明-曝光、阴影、高光 - 色彩和谐-色彩平衡和调色板 - 景深-聚焦和散景质量 - 内容评分-主题和兴趣

• 灵活输入：根据文件路径或base64编码数据对图像进行评分
• 基于CLIP：基于OpenAI的CLIP ViT-B/32视觉编码器构建
• 0-5刻度：所有分数都标准化为直观的0-5范围（0=差，5=优）

安装

先决条件

• Python 3.10或更高版本
• pip或uv包管理器

从源代码安装

# Clone the repository
git clone https://github.com/maroun2/aesthetic-mcp.git
cd aesthetic-mcp

# Create a virtual environment (recommended)
python3 -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate

# Install the package in editable mode (required)
pip install -e .

可选：下载微调砝码

服务器可以使用现成的基本CLIP模型。为了使用微调模型获得更好的结果：

1. 下载 model.pt 从 https://huggingface.co/rsinema/aesthetic-scorer
2. 将其放置在项目根目录中或更新中的模型加载路径 src/aesthetic_scorer_mcp/server.py

用法

运行服务器

安装软件包后 pip install -e .，运行：

# Activate your virtual environment first
source venv/bin/activate  # On Windows: venv\Scripts\activate

# Start the server
python -m aesthetic_scorer_mcp.server

服务器将通过stdio（标准输入/输出）等待JSON-RPC消息。

使用Claude Desktop进行配置

将此添加到您的Claude Desktop MCP设置配置文件中：

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json 视窗: %APPDATA%\Claude\claude_desktop_config.json Linux: ~/.config/Claude/claude_desktop_config.json

{
  "mcpServers": {
    "aesthetic-scorer": {
      "command": "/path/to/aesthetic-mcp/venv/bin/python",
      "args": ["-m", "aesthetic_scorer_mcp.server"]
    }
  }
}

替换 /path/to/aesthetic-mcp/venv/bin/python 使用您的实际虚拟环境Python路径。

备注：确保您已安装了以下软件包 pip install -e . 在配置Claude Desktop之前，请先在虚拟环境中进行配置。

配置后，重新启动Claude Desktop以加载MCP服务器。

可用工具

1. score_image

根据文件路径对图像进行评分。

参数：

• image_path （string，必填）：图像文件的路径

例子：

{
  "image_path": "/path/to/image.jpg"
}

输出：

Aesthetic Scores (0-5 scale):

Overall Aesthetic: 4.23
Technical Quality: 4.56
Composition: 3.89
Lighting: 4.12
Color Harmony: 4.34
Depth of Field: 3.67
Content: 4.01

2. score_image_base64

根据base64编码数据对图像进行评分。

参数：

• base64_data （字符串，必填）：Base64编码图像数据

例子：

{
  "base64_data": "iVBORw0KGgoAAAANSUhEUgAAAA..."
}

与Claude Desktop一起使用

配置后，您可以要求Claude分析图像：

为单张图片打分：

Can you score the aesthetic quality of /path/to/my/image.jpg?

比较多个图像：

Compare the aesthetic scores of image1.jpg and image2.jpg

分析具体维度：

What's the composition score for this photo?

测试服务器

回声技术快速测试

在将MCP服务器与Claude Desktop集成之前，您可以使用echo技术对其进行测试。确保你有：

1. 已激活您的虚拟环境
2. 安装了以下软件包 pip install -e .

列出可用工具：

echo '{"jsonrpc":"2.0","id":1,"method":"tools/list","params":{}}' | python3 -m aesthetic_scorer_mcp.server

给图像打分：

echo '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"score_image","arguments":{"image_path":"/absolute/path/to/your/image.jpg"}}}' | python3 -m aesthetic_scorer_mcp.server

重要提示：

• 使用图像文件的绝对路径（例如。， /home/user/pictures/photo.jpg)
• 每个echo命令都会启动一个新的服务器实例并加载模型（需要几秒钟）
• 服务器将日志输出到stderr，JSON-RPC响应输出到stdout
• 模型加载消息（INFO日志）正常，表示服务器正在启动

真实图像示例

# Activate virtual environment
source venv/bin/activate

# Test with your image (replace with actual path)
echo '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"score_image","arguments":{"image_path":"/home/user/photos/landscape.jpg"}}}' | python -m aesthetic_scorer_mcp.server 2>/dev/null | jq

这 2>/dev/null 抑制模型加载日志，以及 jq 格式化JSON输出（使用安装 apt install jq 或 brew install jq).

命令行用法

你也可以在Python中直接使用记分器：

from aesthetic_scorer_mcp.server import score_image

# Score an image
scores = score_image('my_photo.jpg')
print(scores)
# Output: {'aesthetic': 4.23, 'quality': 4.56, 'composition': 3.89, ...}

型号详细信息

• 基础模型：CLIP ViT-B/32（视觉转换器）
• 已微调：用于美学评分的PARA数据集
• 建筑：CLIP视觉编码器+7个独立的预测头
• 分数范围：每个维度为0-5
• 输入：RGB图像（任何大小，自动预处理）

发展

项目结构

aesthetic-mcp/
├── src/
│   └── aesthetic_scorer_mcp/
│       ├── __init__.py
│       ├── server.py       # MCP server implementation
│       └── model.py        # AestheticScorer model definition
├── pyproject.toml          # Project configuration
├── requirements.txt        # Python dependencies
├── README.md              # This file
└── .gitignore

技术说明

GPU支持

服务器会自动检测并使用CUDA（如果可用）。对于仅CPU推理：

• 模型加载将自动回退到CPU
• 推理速度较慢，但功能齐全

演出

• 首次运行：模型下载和初始化（~350MB）
• 后续运行：快速推理（GPU上每张图像的毫秒数）
• 记忆：~ 1GB RAM/VRAM用于模型权重

提高准确性

目前使用基础CLIP模型。为了通过微调权重获得更好的结果：

1. 下载微调模型：

   cd aesthetic-mcp
   wget https://huggingface.co/rsinema/aesthetic-scorer/resolve/main/model.pt

1. 如果满足以下条件，模型将自动加载 model.pt 存在于项目根目录中

许可证

MIT许可证-请参阅 原始模型存储库 针对特定型号的许可。

学分

• 型号： rsinema/审美评分
• 基础架构：OpenAI CLIP
• 训练数据集：PARA（美学数据集）

贡献

欢迎投稿！请随时提交问题或拉取请求。

故障排除

模型加载失败

• 确保安装了所有依赖项： pip install -r requirements.txt
• 检查Python版本（需要3.10+）
• 验证系统的PyTorch安装

内存不足错误

• 评分前减小图像大小
• 使用CPU而不是GPU进行推理
• 关闭其他应用程序以释放内存

导入错误或“找不到模块”错误

• 确保您已安装该软件包： pip install -e .
• 验证虚拟环境是否已激活
• 重新安装软件包： pip install -e . --force-reinstall