radoone/nameday-mcp

🎉 Nameday MCP Server

A powerful Model Context Protocol (MCP) server providing comprehensive nameday information for 11+ countries. Perfect for AI assistants, chatbots, and applications needing cultural calendar data.

🌐 Try Online Version

👉 https://nameday-mcp.vercel.app/

No installation required! The online version is ready to use immediately.

✨ Features

• 🌍 Multi-country support - 11+ countries with comprehensive nameday calendars
• 🔍 Smart name search - Find when any name celebrates with flexible matching
• 📅 Date lookup - Discover all names celebrating on specific dates
• ⚡ Real-time queries - Get today's nameday celebrations instantly
• 🎯 Accurate data - Traditional and culturally authentic nameday information
• 🚀 Multiple access methods - Online hosted version + local installation options
• 📊 Resources support - Access locale information and statistics via MCP resources
• 🎛️ Prompts support - Pre-built prompts for common nameday queries
• 📝 Logging support - Comprehensive logging for debugging and monitoring

🌍 Supported Countries

Note: Russian and Bulgarian calendars include comprehensive Orthodox feast days and traditional names.

🔧 Available Tools

1. find_name_day

Find when a specific name celebrates its nameday.

{
  "tool": "find_name_day",
  "args": {
    "name": "Radovan",
    "locale": "sk"
  }
}

2. find_names_by_date

Discover which names celebrate on a specific date.

{
  "tool": "find_names_by_date",
  "args": {
    "month": 6,
    "day": 29,
    "locale": "sk"
  }
}

3. get_today_name_days

Get today's nameday celebrations.

{
  "tool": "get_today_name_days",
  "args": {
    "locale": "sk",
    "random_string": "dummy"
  }
}

📊 Available Resources

The server provides contextual information through MCP resources:

• nameday://supported-locales - List of all supported country locales
• nameday://locale-info/sk - Information about Slovakia nameday calendar
• nameday://locale-info/cz - Information about Czech Republic nameday calendar
• nameday://statistics - Server statistics and available features

🎛️ Available Prompts

Pre-built prompts for common nameday queries:

• find-nameday - Find when a specific name has its nameday
• names-on-date - Find which names celebrate on a specific date
• today-namedays - Get today's nameday celebrations

Example Prompt Usage

{
  "prompt": "find-nameday",
  "arguments": {
    "name": "Radovan",
    "locale": "sk"
  }
}

🚀 Quick Start

Option 1: Use Online Version (Recommended)

Simply add this to your Claude Desktop configuration:

{
  "mcpServers": {
    "nameday-mcp-server": {
      "command": "npx",
      "args": [
        "mcp-remote",
        "https://nameday-mcp.vercel.app/sse"
      ]
    }
  }
}

Option 2: Local Installation

1. Install dependencies:

   npm install
   

2. Build the project:

   npm run build
   

3. Add to Claude Desktop:

   {
     "mcpServers": {
       "nameday-mcp-server": {
         "command": "node",
         "args": ["./dist/index.js"],
         "cwd": "/path/to/nameday-mcp"
       }
     }
   }
   

📚 API Usage

Direct API Testing

Test the online version directly:

curl -X POST https://nameday-mcp.vercel.app/api/tools \
  -H "Content-Type: application/json" \
  -d '{
    "tool": "find_name_day",
    "args": {
      "name": "Radovan",
      "locale": "sk"
    }
  }'

Available Endpoints

• GET / - Interactive documentation
• GET /health - Server health check
• GET /api/tools - List available tools
• POST /api/tools - Execute tools
• GET /sse - MCP Server-Sent Events endpoint

💡 Example Queries

Ask your AI assistant:

• "When is Radovan's nameday in Slovakia?"
• "Who celebrates nameday on June 29th in Czech Republic?"
• "What names have nameday today in Poland?"
• "Find all Hungarian names celebrating in July"

🛠️ Development

Local Development

STDIO Mode (for Claude Desktop):

npm run dev

HTTP Mode (for testing):

npm run dev:sse

Project Structure

src/
├── index.ts          # Main server and HTTP endpoints
├── server.ts         # MCP server logic and tools
├── locale-nameday.ts # Nameday lookup functions
└── data/             # Nameday calendars for each country
    ├── sk.json       # Slovakia
    ├── cz.json       # Czech Republic
    └── ...           # Other countries

🎯 Use Cases

• AI Assistants - Add cultural calendar knowledge
• Chatbots - Provide nameday information in conversations
• Applications - Integrate nameday features
• Personal Assistants - Remind about friends' namedays

📖 More Information

• Documentation: Visit https://nameday-mcp.vercel.app/
• Source Code: GitHub Repository
• Issues: Report bugs or request features on GitHub

📝 License

MIT License - see file for details.

🌟 Ready to get started? Try the online version or configure it with your mcp host today!