MCP Image Recognition Server

# MCP Image Recognition Server (Python) An MCP server implementation in Python providing image recognition capabilities using various LLM providers (Gemini, OpenAI, Qwen/Tongyi, Doubao, etc.). ## Features - **Image Recognition**: Describe images or answer questions about them. - **Multi-Model Support**: Dynamically switch between Gemini, GPT-4o, Qwen-VL, Doubao, etc. - **Flexible**: Accepts image URLs or Base64 data. ## Quick Setup (Recommended) We provide automated scripts to set up the environment and dependencies in one click. ### Linux / macOS ```bash git clone https://github.com/glasses666/mcp-image-recognition-py.git cd mcp-image-recognition-py ./setup.sh ``` ### Windows 1. Clone or download this repository. 2. Double-click `setup.bat`. After the script finishes, simply edit the `.env` file with your API keys. --- ## Installation & Usage (Manual) If you prefer manual installation or want to use `uv`: ### Prerequisites - Python 3.10 or higher - An API Key for your preferred model provider (Google Gemini, OpenAI, Aliyun DashScope, etc.) --- ### Method 1: Using `uv` (Recommended) [uv](https://github.com/astral-sh/uv) is an extremely fast Python package manager. #### 1. Run directly with `uv run` You don't need to manually create a virtual environment. ```bash # Clone the repo git clone https://github.com/glasses666/mcp-image-recognition-py.git cd mcp-image-recognition-py # Create .env file with your API keys cp .env.example .env # Edit .env with your keys # Run the server uv run server.py ``` #### 2. Using `uvx` (for ephemeral execution) If you want to run it without cloning the repo explicitly (experimental support via git): ```bash # Note: You still need to provide environment variables. # It's easier to clone and use 'uv run' for persistent config via .env uvx --from git+https://github.com/glasses666/mcp-image-recognition-py mcp-image-recognition ``` --- ### Method 2: Standard Python (pip) #### Linux / macOS 1. **Clone and Setup:** ```bash git clone https://github.com/glasses666/mcp-image-recognition-py.git cd mcp-image-recognition-py python3 -m venv venv source venv/bin/activate pip install -r requirements.txt ``` 2. **Configure:** ```bash cp .env.example .env # Edit .env and add your API keys ``` 3. **Run:** ```bash python server.py ``` #### Windows 1. **Clone and Setup:** ```powershell git clone https://github.com/glasses666/mcp-image-recognition-py.git cd mcp-image-recognition-py python -m venv venv .\venv\Scripts\activate pip install -r requirements.txt ``` 2. **Configure:** ```powershell copy .env.example .env # Edit .env and add your API keys ``` 3. **Run:** ```powershell python server.py ``` --- ## Configuration Create a `.env` file in the project root based on `.env.example`: ### 1. For Google Gemini (Recommended for speed/cost) Get an API key from [Google AI Studio](https://aistudio.google.com/). ```env GEMINI_API_KEY=your_google_api_key DEFAULT_MODEL=gemini-1.5-flash ``` ### 2. For Tongyi Qianwen (Qwen - Alibaba Cloud) Get an API key from [Aliyun DashScope](https://dashscope.console.aliyun.com/). ```env OPENAI_API_KEY=your_dashscope_api_key OPENAI_BASE_URL=https://dashscope.aliyuncs.com/compatible-mode/v1 DEFAULT_MODEL=qwen-vl-max ``` ### 3. For Doubao (Volcengine) Get an API key from [Volcengine Ark](https://www.volcengine.com/product/ark). ```env OPENAI_API_KEY=your_volcengine_api_key OPENAI_BASE_URL=https://ark.cn-beijing.volces.com/api/v3 DEFAULT_MODEL=doubao-pro-32k ``` --- ## Agent AI Configuration (Claude Desktop, etc.) To use this server with an MCP client (like Claude Desktop), add it to your configuration file. ### Configuration File Paths - **macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json` - **Windows**: `%APPDATA%\Claude\claude_desktop_config.json` - **Linux**: `~/.config/Claude/claude_desktop_config.json` (if available) ### Configuration JSON **Option A: Using `uv` (Easiest)** If you have `uv` installed, you can let it handle the environment. ```json { "mcpServers": { "image-recognition": { "command": "/path/to/uv", "args": [ "run", "--directory", "/absolute/path/to/mcp-image-recognition-py", "server.py" ], "env": { "GEMINI_API_KEY": "your_gemini_key_here", "OPENAI_API_KEY": "your_openai_key_here", "OPENAI_BASE_URL": "https://api.openai.com/v1", "DEFAULT_MODEL": "gemini-1.5-flash" } } } } ``` **Option B: Standard Python Venv** Ensure you provide the **absolute path** to the python executable in your virtual environment. ```json { "mcpServers": { "image-recognition": { "command": "/absolute/path/to/mcp-image-recognition-py/venv/bin/python", "args": [ "/absolute/path/to/mcp-image-recognition-py/server.py" ], "env": { "GEMINI_API_KEY": "your_gemini_key_here", "OPENAI_API_KEY": "your_openai_key_here", "OPENAI_BASE_URL": "https://api.openai.com/v1", "DEFAULT_MODEL": "gemini-1.5-flash" } } } } ``` *Windows Note:* For paths, use double backslashes `\\` (e.g., `C:\\Users\\Name\\...`). --- ## Usage Tool ### `recognize_image` Analyzes an image and returns a text description. **Parameters:** - `image` (string, required): The image to analyze. Supports: - HTTP/HTTPS URLs (e.g., `https://example.com/cat.jpg`) - Base64 encoded strings (with or without `data:image/...;base64,` prefix) - `prompt` (string, optional): Specific instruction. Default: "Describe this image". - `model` (string, optional): Override the default model for this specific request. ## License MIT