pet-adoption-mcp
Version:
A Model Context Protocol (MCP) server that helps users find adoptable pets through the Petfinder API
186 lines (138 loc) • 6.61 kB
Markdown
# MCP server to for pet adoption
A Model Context Protocol (MCP) server that helps users find adoptable pets through the Petfinder API.
## 🐾 Features
- **Pet Search**: Search for adoptable animals using various criteria (type, location, age, breed, etc.)
- **Smart Validation**: Validates search parameters against available animal types, breeds, and colors
- **Location Support**: Search by city/state, zipcode, or latitude/longitude coordinates
- **Adoption Assistance**: Collects user information and helps draft personalized emails to shelters
- **MCP Integration**: Built as a Model Context Protocol server for seamless AI assistant integration
## 🚀 Quick Start
### Prerequisites
- Node.js (v18 or higher)
- Petfinder API credentials
### Get Petfinder API Credentials
You'll need Petfinder API credentials to use this server:
1. Create an account at [Petfinder for Developers](https://www.petfinder.com/developers/)
2. Create a new application to get your API key and secret
### Usage Options
#### Option 1: Using Claude Desktop (Recommended)
1. Add the pet adoption server to your `claude_desktop_config.json`:
```json
{
"mcpServers": {
"PetAdoptionFinder": {
"command": "npx",
"args": [
"pet-adoption-mcp",
"--apiKey",
"YOUR_API_KEY",
"--secretKey",
"YOUR_SECRET_KEY"
]
}
}
}
```
2. Replace `YOUR_API_KEY` with your Petfinder API `client_id`
3. Replace `YOUR_SECRET_KEY` with your Petfinder API `client_secret`
4. Restart Claude Desktop
#### Option 2: Local Development
For developers who want to run it locally:
1. Clone the repository:
```bash
git clone https://github.com/sqing73/mcp-server-for-pet-adoption.git
cd mcp-server-for-pet-adoption
```
2. Install dependencies:
```bash
npm install
```
3. Build the project:
```bash
npm run build
```
4. Add the pet adoption server to your `claude_desktop_config.json`:
```json
{
"mcpServers": {
"PetAdoptionFinder": {
"command": "node",
"args": [
"/PATH/dist/index.js",
"--apiKey",
"YOUR_API_KEY",
"--secretKey",
"YOUR_SECRET_KEY"
]
}
}
}
```
5. Replace `PATH` with your path to `mcp-server-for-pet-adoption`
6. Replace `YOUR_API_KEY` with your Petfinder API `client_id`
7. Replace `YOUR_SECRET_KEY` with your Petfinder API `client_secret`
8. Restart Claude Desktop
## 🔧 API Reference
### Search Adoptable Animals
The main tool provided by this server is `search_adoptable_animals`, which accepts the following parameters:
#### Required Parameters
- `type`: Animal type (e.g., "Dog", "Cat", "Rabbit", etc.)
- `location`: Search location in one of these formats:
- `{ city: "New York", state: "NY" }`
- `{ zipcode: "10001" }`
- `{ latitude: "40.7128", longitude: "-74.0060" }`
#### Optional Parameters
- `age`: Animal age (`baby`, `young`, `adult`, `senior`)
- `gender`: Animal gender (`male`, `female`)
- `coat`: Coat type (`short`, `medium`, `long`, `wire`, `hairless`, `curly`)
- `color`: Animal color (validated against available colors for the animal type)
- `breed`: Animal breed (validated against available breeds for the animal type)
- `size`: Animal size (`small`, `medium`, `large`, `xlarge`)
- `good_with_children`: Boolean - whether the animal is good with children
- `good_with_dogs`: Boolean - whether the animal is good with dogs
- `good_with_cats`: Boolean - whether the animal is good with cats
- `house_trained`: Boolean - whether the animal is house trained
- `declawed`: Boolean - whether the animal is declawed
- `special_needs`: Boolean - whether the animal has special needs
- `distance`: Number - search radius in miles (default: 10)
- `sort`: Sort order (`recent`, `distance`, `-recent`, `-distance`)
- `before`/`after`: ISO8601 date-time strings for filtering by publication date
### User Information Collection
The server also provides a prompt `user_information_collector_for_shelter_email` that helps collect user information for drafting shelter contact emails. It gathers:
- Preferred animals from recommendations
- Household information (children, other pets)
- Pet ownership experience
- Housing situation (renting vs. owning)
## 🛠️ Development
### Scripts
- `npm run build`: Compile TypeScript to JavaScript
- `npm run dev`: Watch mode for development
- `npm start`: Run the compiled server
### TODO
- [ ] **Image-based Animal Search**: Add functionality to find similar animals by uploading an image
- Use image embedding and vector database with distance metrics to find most similar animals
- Provide visual similarity scoring for better matches
## 📝 Example Usage
The server is designed to work with AI assistants that support the Model Context Protocol. When integrated, users can ask questions like:
- "Find adoptable dogs near New York City"
- "Show me small cats that are good with children"
- "Search for senior dogs in zipcode 90210"
The server will validate the request, search the Petfinder API, and provide recommendations with relevant information and URLs.
## 📸 Demo
### Claude Desktop Comparison
| With MCP Server | Without MCP Server |
|----------------|-------------------|
|  |  |
### Video Demonstration
[Watch Demo Video](https://github.com/sqing73/mcp-server-for-pet-adoption/raw/refs/heads/main/assets/ClaudeDesktopWithMCPServerVideo.mov)
## 🙏 Acknowledgments
This project is made possible by the [Petfinder API](https://www.petfinder.com/developers/), which provides comprehensive data about adoptable pets from thousands of animal shelters and rescue organizations across the United States and Canada.
- **Petfinder API**: For providing the extensive database of adoptable animals and shelter information
- **Petfinder Organization**: For their mission to help pets find loving homes
- **Animal Shelters & Rescues**: For their tireless work in caring for and rehoming animals
## 📄 License
This project is licensed under the MIT License.
## 🔗 Links
- [Petfinder API Documentation](https://www.petfinder.com/developers/)
- [Model Context Protocol](https://modelcontextprotocol.io/)
- [Petfinder for Developers](https://www.petfinder.com/developers/)