MCP server for AI-powered image recognition and description using OpenAI vision models.
npm install image-recognition-mcpA Model Context Protocol (MCP) server that provides AI-powered image recognition and description capabilities using OpenAI's vision models.
This MCP server enables AI assistants to analyze and describe images through a simple URL-based interface. It leverages OpenAI's powerful vision models to provide detailed descriptions of images, making it easy to integrate image analysis capabilities into your AI workflows.
- Image Analysis: Analyze images from URLs and get detailed descriptions
- OpenAI Integration: Uses OpenAI's latest vision models for accurate image recognition
- MCP Protocol: Fully compatible with the Model Context Protocol standard
- TypeScript: Built with TypeScript for type safety and better development experience
- Simple API: Easy-to-use interface for image description requests
- Node.js 18+
- npm or yarn
- OpenAI API key
To use this server with an MCP client, add the following configuration:
``json`
{
"mcpServers": {
"image-recognition": {
"command": "npx",
"args": ["-y", "@mcp-s/image-recognition-mcp"],
"env": {
"OPENAI_API_KEY": "your-actual-openai-api-key-here"
}
}
}
}
⚠️ IMPORTANT: The env section with your OpenAI API key is required - this is the only way the MCP server can function.
#### describe-image
Analyzes an image from a URL and provides a detailed description.
Parameters:
- imageUrl (string): The URL of the image to analyze
Example:
`json`
{
"tool": "describe-image",
"arguments": {
"imageUrl": "https://example.com/image.jpg"
}
}
Response:
`json`
{
"content": [
{
"type": "text",
"text": "The image shows a beautiful sunset over a mountain landscape with vibrant orange and pink colors in the sky..."
}
]
}
This MCP server can be integrated with various AI assistants that support the MCP protocol, such as:
- Claude Desktop
- Other MCP-compatible AI systems
`
image-recognition-mcp/
├── src/
│ └── index.ts # Main server implementation
├── dist/ # Compiled JavaScript output
├── package.json # Project dependencies and scripts
├── tsconfig.json # TypeScript configuration
└── README.md # This file
The server includes robust error handling for:
- Invalid image URLs
- Network connectivity issues
- OpenAI API errors
- Invalid input parameters
Server fails to start or doesn't work:
- ✅ Check if OpenAI API key is set: This is the #1 cause of issues
`bash`
echo $OPENAI_API_KEY # Should show your API key
- ✅ Verify API key is valid: Test with OpenAI's API directly
- ✅ Check API key has sufficient credits: Ensure your OpenAI account has available credits
"Authentication failed" errors:
- The OpenAI API key is missing or invalid
- Set the environment variable: export OPENAI_API_KEY="your-key"
1. Fork the repository
2. Create a feature branch (git checkout -b feature/amazing-feature)git commit -m 'Add some amazing feature'
3. Commit your changes ()git push origin feature/amazing-feature
4. Push to the branch ()
5. Open a Pull Request
This project is licensed under the ISC License. See the LICENSE` file for details.
For support, please open an issue in the GitHub repository or contact the maintainer.