AI导哈

图像识别服务

一个基于Model Context Protocol (MCP)的服务器，提供AI驱动的图像识别和描述功能，支持OpenAI兼容的视觉模型。

  • by akirose
  • TypeScript
  • 本地部署
  • 6 星标
  • 更新于
在 GitHub 查看 akirose/image-recognition-mcp

使用说明

图像识别MCP服务器

一种模型上下文协议（MCP）服务器，使用OpenAI兼容的视觉模型提供AI驱动的图像识别和描述功能。

概述

此MCP服务器使AI助手能够通过简单的基于URL的界面分析和描述图像。它支持OpenAI的视觉模型以及与OpenAI兼容的本地模型（如LM Studio、Ollama等），提供图像的详细描述，并使图像分析功能易于集成到您的AI工作流程中。

特性

  • 图像分析：分析URL中的图像并获取详细描述
  • 灵活的模型支持：适用于OpenAI的视觉模型和OpenAI兼容的本地模型（LM Studio、Ollama等）
  • MCP协议：与模型上下文协议标准完全兼容
  • TypeScript：使用TypeScript构建，实现类型安全和更好的开发体验
  • 简单API：易于使用的图像描述请求界面

安装

先决条件

  • Node.js 18+
  • npm或纱线
  • OpenAI API密钥或本地视觉模型服务器（例如，LM Studio、Ollama）

MCP客户端配置

要将此服务器与MCP客户端一起使用，请添加以下配置：

{
  "mcpServers": {
    "image-recognition": {
      "command": "npx",
      "args": ["-y", "@akirose/image-recognition-mcp"],
      "env": {
        "OPENAI_API_KEY": "your-actual-openai-api-key-here"
      }
    }
  }
}

要允许从任何路径访问图像文件，请设置 ALLOW_ALL_PATHS 到 true:

{
  "mcpServers": {
    "image-recognition": {
      "command": "npx",
      "args": ["-y", "@akirose/image-recognition-mcp"],
      "env": {
        "OPENAI_API_KEY": "your-actual-openai-api-key-here",
        "ALLOW_ALL_PATHS": "true"
      }
    }
  }
}

⚠️ 重要： 这 env API密钥的部分-这是MCP服务器运行的唯一方式。对于本地模型，您可以使用任何占位符值 OPENAI_API_KEY 并配置 OPENAI_BASE_URL 指向您的本地服务器。

环境变量

服务器支持以下环境变量：

  • OPENAI_API_KEY -您的OpenAI API密钥，或使用本地模型时的任何占位符值（必需）
  • OPENAI_BASE_URL -OpenAI API或与OpenAI兼容的API服务器的基本URL（可选，默认为OpenAI的官方API）
    • LM Studio示例： "http://127.0.0.1:1234/v1"
    • Ollama的例子： "http://localhost:11434/v1"
  • OPENAI_MODEL -用于图像识别的视觉模型（可选，默认为“gpt-5-mini”）
    • 对于OpenAI： "gpt-5-mini", "gpt-4o", "gpt-4o-mini"等等。
    • 对于本地型号： "llava", "qwen/qwen3-vl-4b"，或任何本地可用的视觉模型
  • ALLOWED_IMAGE_PATHS -允许的本地文件路径的逗号分隔列表（可选，默认为“./images，./reassets”）
    • 例子： "./images,./assets,./downloads"
  • ALLOW_ALL_PATHS -设置为“true”以允许从任何路径访问图像文件。启用后，出于安全考虑，只允许使用图像文件扩展名（.jpg、.jpeg、.png、.gif、.webp）（可选，默认为false）
  • ALLOWED_DOMAINS -逗号分隔的允许URL域列表，以增强安全性（可选，默认允许所有域）
    • 例子： "example.com,cdn.example.com,images.example.org"
    • 未设置时：允许所有域
    • 设置时：仅允许指定的域用于基于URL的图像请求

用法

可用工具

describe-image

分析来自URL或本地文件路径的图像，并提供详细描述。

参数：

  • imageUrl （string）：要分析的图像的URL，或本地文件路径
  • prompt （字符串，可选）：询问图像的问题或提示（默认为“此图像中有什么？”）

URL示例：

{
  "tool": "describe-image",
  "arguments": {
    "imageUrl": "https://example.com/image.jpg",
    "prompt": "what's in this image?"
  }
}

本地文件示例：

{
  "tool": "describe-image",
  "arguments": {
    "imageUrl": "./images/my-image.png",
    "prompt": "Describe the objects in this image"
  }
}

答复：

{
  "content": [
    {
      "type": "text",
      "text": "The image shows a beautiful sunset over a mountain landscape with vibrant orange and pink colors in the sky..."
    }
  ]
}

与AI助手集成

此MCP服务器可以与支持MCP协议的各种AI助手集成，例如：

  • 克劳德桌面
  • 其他与MCP兼容的AI系统

发展

项目结构

image-recognition-mcp/
├── src/
│   ├── index.ts                # Main server implementation
│   ├── path-validator.ts       # Path validation and security functions
│   └── image-processor.ts      # Image processing utilities
├── test/
│   ├── index.test.ts           # Unit tests
│   ├── describe-image-integration.test.ts  # Integration tests
│   ├── test.png                # Test image
│   └── README.md               # Test documentation
├── dist/                       # Compiled JavaScript output
├── package.json                # Project dependencies and scripts
├── tsconfig.json               # TypeScript configuration
└── README.md                   # This file

运行测试

该项目包括单元测试和集成测试：

# Run all tests
npm test

# Run unit tests only
npm run test:unit

# Run integration tests with local OpenAI-compatible server
npm run test:integration

集成测试要求：

  • 上正在运行与OpenAI兼容的API服务器 http://127.0.0.1:1234/v1
  • 服务器应支持视觉模型（例如qwen/qwen3-vl-4b）
  • 您可以使用LM Studio、Ollama或其他兼容的服务器
  • 集成测试使用 OPENAI_BASE_URL 和 OPENAI_MODEL 环境变量

集成测试将：

  • 测试对视觉模型的实际API调用
  • 使用测试图像验证图像处理(test/test.png)
  • 使用默认和自定义提示验证完整的MCP工具工作流程
  • 测试错误处理和边缘情况

安全功能

该服务器包括几个安全功能：

  • 路径验证：限制对允许目录的本地文件访问
  • 扩展验证：仅允许特定的图像文件扩展名（.jpg、.jpeg、.png、.gif、.webp）
  • 域限制：增强安全性的可选URL域白名单
  • 文件存在性检查：在处理之前验证文件是否存在

错误处理

该服务器包括强大的错误处理功能，用于：

  • 图像URL无效
  • 未经授权的文件路径或域
  • 网络连接问题
  • OpenAI API错误
  • 输入参数无效
  • 不支持的文件格式

故障排除

常见问题

服务器无法启动或无法工作：

  • ✅ 检查是否设置了OpenAI API密钥：这是问题的首要原因
    echo $OPENAI_API_KEY  # Should show your API key
  • ✅ 验证API密钥是否有效：直接使用OpenAI的API进行测试
  • ✅ 检查API密钥是否有足够的信用：确保您的OpenAI帐户有可用积分

“身份验证失败”错误：

  • OpenAI API密钥丢失或无效
  • 设置环境变量： export OPENAI_API_KEY="your-key"

贡献

  1. 分叉存储库
  2. 创建要素分支(git checkout -b feature/amazing-feature)
  3. 提交您的更改(git commit -m 'Add some amazing feature')
  4. 推到分支(git push origin feature/amazing-feature)
  5. 打开拉取请求

许可证

该项目根据MIT许可证获得许可。请参阅 LICENSE 文件以获取详细信息。

支持

如需支持，请在GitHub存储库中打开问题或联系维护人员。

相关 MCP