Surprise Buddy — Claude Code MCP server: what it does, how to install
Surprise Buddy connects AI assistants to a country-scoped gift database with direct links to real marketplace products.
no license 4,734 installs updated 2026-05-16
claude mcp add --transport http mcp-server https://mcp-server--surprise-buddy.run.toolsWhat Surprise Buddy does
Surprise Buddy exposes gift recommendation queries to your assistant via MCP. The service matches recipients to items from marketplaces like Amazon, Etsy, Bol.com, Allegro, and Otto, returning item titles, images, prices, and links ready to open.
Search queries through find_gifts require an ISO-2 country code. That parameter is mandatory because results adapt to local currencies and regionally available stores. Companion tools list supported regions, occasion codes, hobby tags, and color filters before running a search.
Authentication is omitted entirely, making the server publicly accessible. Rate limits can still apply under heavy traffic.
What it helps with
- search for gifts tailored to a specific country and currency
- fetch direct product links from marketplaces like Etsy or Allegro
- inspect valid occasion and hobby tags before querying gifts
- match presents based on recipient interests and preferred colors
Example prompts for the agent
- Find a birthday gift for a coffee lover in Germany using Surprise Buddy
- List the countries and occasions supported by Surprise Buddy
- Suggest a gift in France for someone interested in board games
How to install Surprise Buddy
Platform CLI: remote server
claude mcp add --transport http mcp-server https://mcp-server--surprise-buddy.run.toolsPlatform CLI: remote server
codex mcp add surprise-buddy --url https://mcp-server--surprise-buddy.run.toolsConfig file
{
"mcpServers": {
"surprise-buddy": {
"url": "https://mcp-server--surprise-buddy.run.tools"
}
}
}Config file
{
"servers": {
"surprise-buddy": {
"type": "http",
"url": "https://mcp-server--surprise-buddy.run.tools"
}
}
}Platform CLI: remote server
gemini mcp add -t http surprise-buddy https://mcp-server--surprise-buddy.run.toolsStep by step, with commands for each platform: How to add an MCP server to Claude Code, Codex, Cursor, VS Code, Gemini CLI and more
Questions about Surprise Buddy
How do I install Surprise Buddy in Claude Code?
Run claude mcp add --transport http surprise-buddy https://mcp-server--surprise-buddy.run.tools in your terminal.
What tools does Surprise Buddy provide?
It provides find_gifts alongside catalog inspectors: list_supported_countries, list_supported_occasions, list_supported_interests, and list_supported_colors.
Does Surprise Buddy require an API key?
No authentication is necessary to connect; the endpoint at https://mcp-server--surprise-buddy.run.tools is public.