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
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:

   {
     "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:

git clone https://github.com/sqing73/mcp-server-for-pet-adoption.git
cd mcp-server-for-pet-adoption

2. Install dependencies:

npm install

3. Build the project:

npm run build

4. Add the pet adoption server to your claude_desktop_config.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

🙏 Acknowledgments

This project is made possible by the Petfinder API, 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
• Model Context Protocol
• Petfinder for Developers