Name Origin Predictor

Predicts the national origin of names using the Nationalize.io API, offering both individual and batch processing with probability scores for demographic analysis and cultural research.

Installation Instructions

README: https://github.com/allglenn/mcp-name-origin-server

Name Origin Predictor

A Python-based MCP (Model Context Protocol) server that predicts the origin of names using the Nationalize.io API.

Features

• Predict the origin of a single name
• Batch prediction for multiple names
• Real-time API integration with Nationalize.io
• MCP protocol support for seamless integration

Prerequisites

• Python 3.x
• Virtual environment (recommended)
• Required packages:
  • httpx
  • mcp-server

Installation

1. Clone the repository:

git clone https://github.com/allglenn/mcp-name-origin-server.git
cd mcp-name-origin-server

2. Create and activate a virtual environment:

python3 -m venv venv
source venv/bin/activate  # On Unix/macOS
# or
.\venv\Scripts\activate  # On Windows

3. Install dependencies:

pip install httpx

Configuration

1. Create a claude_desktop_config.json file:

{
    "mcpServers": {
        "origin": {
            "command": "source",
            "args": [
                "venv/bin/activate",
                "&&",
                "python3",
                "-u",
                "mcp-server.py"
            ],
            "shell": true,
            "env": {
                "PYTHONPATH": ".",
                "PYTHONUNBUFFERED": "1"
            }
        }
    },
    "defaultServer": "origin",
    "version": "0.1.0"
}

Usage

Starting the Server

python mcp-server.py

Available Methods

1. predict_origin(name: str): Predicts the origin of a single name

   • Input: A string containing the name
   • Output: JSON object with country predictions and probabilities

2. batch_predict(names: list[str]): Predicts origins for multiple names

   • Input: A list of names
   • Output: JSON object with predictions for each name

Example Response

{
    "name": "glenn",
    "country": [
        {
            "country_id": "US",
            "probability": 0.421
        },
        {
            "country_id": "AU",
            "probability": 0.044
        }
    ]
}

API Reference

This project uses the Nationalize.io API to predict name origins. The API is free for basic usage with rate limits.

Error Handling

The server handles various error cases:

• Invalid name format
• API connection issues
• Rate limiting
• Server errors

Development

To contribute to this project:

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Submit a pull request

License

This project is licensed under the MIT License - see the LICENSE file for details.

Acknowledgments

• Nationalize.io for providing the name origin prediction API
• MCP protocol for the server implementation framework