mcp-pixabay-server

# MCP Pixabay Server [](https://www.npmjs.com/package/@sadais/mcp-pixabay-server) [](https://opensource.org/licenses/MIT) [](https://github.com/sadais-org/mcp-pixabay-server/actions) A Pixabay API interface server based on [MCP (Model Context Protocol)](https://modelcontextprotocol.github.io/) that allows AI models to search and retrieve images and videos from the Pixabay platform. ## Features - A server implementation fully compliant with MCP protocol specifications - Provides two core tools: - `search_images` - Search for Pixabay image resources - `search_videos` - Search for Pixabay video resources - Supports a rich set of search parameters: keywords, image/video type, orientation, category, color, etc. - Returns complete resource metadata (URL, resolution, tags, etc.) - Supports API key configuration via environment variables ## Installation ### Global Installation ```bash npm install -g @sadais/mcp-pixabay-server ``` ### Project Dependency Installation ```bash npm install @sadais/mcp-pixabay-server --save ``` ## Configuration The server requires a Pixabay API key to function properly. You can set it via environment variables: ```bash export PIXABAY_API_KEY=your_api_key_here ``` If you do not have a Pixabay API key, you can register and obtain one at the [Pixabay API Documentation](https://pixabay.com/api/docs/) page. ## Usage ### As a Command Line Tool ```bash # Start the MCP server mcp-pixabay-server ``` ### Integration with AI Models This server can be integrated with AI models that support the MCP protocol (such as Claude): 1. Start the MCP server 2. Configure the AI model to use this MCP service In environments like Cursor or Anthropic Console using Claude Opus, you can integrate this service by configuring the mcp.json file: ```json "pixabay": { "command": "npx", "args": ["-y", "@sadais/mcp-pixabay-server"], "env": { "PIXABAY_API_KEY": "your_api_key_here" } } ``` Add the above configuration to your mcp.json file, and the AI model will be able to call the Pixabay search functionality via the MCP protocol. ### API Reference #### search_images Search for Pixabay image resources. Parameters: - `query` (required) - Search keywords - `image_type` - Image type ("all", "photo", "illustration", "vector") - `orientation` - Image orientation ("all", "horizontal", "vertical") - `category` - Image category - `colors` - Image colors - `safesearch` - Safe search mode - `page` - Page number - `per_page` - Number of results per page (3-200) #### search_videos Search for Pixabay video resources. Parameters: - `query` (required) - Search keywords - `video_type` - Video type ("all", "film", "animation") - `category` - Video category - `safesearch` - Safe search mode - `page` - Page number - `per_page` - Number of results per page (3-200) ## Development Guide ### Environment Setup ```bash # Clone the repository git clone https://github.com/sadais-org/mcp-pixabay-server.git cd mcp-pixabay-server # Install dependencies npm install # Build the project npm run build # Development mode (auto-compile) npm run watch ``` ### Testing We use Vitest for testing. Run the following command to execute tests: ```bash # Run all tests npm test # Run tests in watch mode npm run test:watch # Generate test coverage report npm run test:coverage ``` ### Code Quality We use ESLint and Prettier to ensure code quality: ```bash # Run code checks npm run lint # Automatically fix code issues npm run lint:fix ``` ### Commit Guidelines We follow the [Conventional Commits](https://www.conventionalcommits.org/en/v1.0.0/) specification to format commit messages. Commit messages should follow this format: ``` type(scope): subject ``` Types must be one of the following: - `feat`: New feature - `fix`: Bug fix - `docs`: Documentation update - `style`: Code style changes (no functional impact) - `refactor`: Code refactoring - `perf`: Performance improvement - `test`: Testing related - `build`: Build system or external dependencies - `ci`: CI configuration and scripts - `chore`: Other changes - `revert`: Revert a commit ### Debugging Since the MCP server communicates via stdio, debugging can be challenging. It is recommended to use the [MCP Inspector](https://github.com/modelcontextprotocol/inspector): ```bash npm run inspector ``` The Inspector will provide a URL that allows you to access debugging tools in your browser. ## Contribution Guidelines We welcome and appreciate any form of contribution! ### Issue Guidelines When creating an issue, please follow these guidelines: 1. Use a clear and concise title to describe the problem or feature 2. For bug reports: - Describe the steps to reproduce the issue - Expected behavior and actual behavior - Environment information (operating system, Node.js version, etc.) - Relevant logs or screenshots 3. For feature requests: - Describe the feature and its purpose - Expected use cases - Implementation suggestions (optional) ### Pull Request Guidelines When submitting a PR, please follow these guidelines: 1. Create a descriptive branch name, such as `feature/add-image-filters` or `fix/api-timeout` 2. Ensure the code passes all tests and code checks 3. The PR title should clearly describe the changes and follow the [Conventional Commits](https://www.conventionalcommits.org/en/v1.0.0/) specification 4. The PR description should include: - Detailed explanation of the changes - Associated issue number (if any) - Testing methods (if applicable) 5. Maintain consistent code style ### Quality Checks Each PR must meet the following quality requirements: - Pass all automated tests - Pass all code checks (ESLint) - Test coverage does not decrease (target coverage ≥70%) - Commit messages conform to the specification ### Development Process 1. Fork the repository and clone it locally 2. Create a new branch for development 3. Commit changes and push to your fork 4. Create a Pull Request to the main repository ## License This project is open source under the MIT License - see the [LICENSE](LICENSE) file for details.