Name Origin Predictor MCP Server

How to use

To use this MCP server with your client, you start the server locally and then invoke the provided methods from your MCP client software. Best results come from starting the server first, then sending requests for either a single name or a list of names.

How to install

# Prerequisites
- Python 3.x
- A virtual environment (recommended)

# Install dependencies (after you have Python installed)
pip install httpx
```

1. Clone the project
```
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
```

4. Start the MCP server locally
```
python mcp-server.py
```

5. Optional: create and customize a configuration file named `claude_desktop_config.json` as described in the configuration section.

Additional sections

Configuration details and environment setup are shown below so you can run the server reliably in your environment. The server is designed to run as a local MCP endpoint that your clients connect to for name-origin predictions.

Configuration is defined in a JSON snippet that specifies a local MCP runtime. It activates the Python virtual environment and runs the MCP server, exposing the required environment variables for proper Python behavior.

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

Notes on usage and behavior

This server uses the Nationalize.io API to predict name origins. It supports two core methods you’ll expose to your MCP client: a single-name prediction and a batch prediction for multiple names. The single-name method returns a list of country predictions with associated probabilities, while the batch method returns predictions for each name in the input list.

Error handling includes checks for invalid input formats, issues connecting to the external API, rate limiting, and general server errors. If you encounter issues, ensure your virtual environment is active, dependencies are installed, and the server process is running.

Environment variables shown in the local configuration include PYTHONPATH and PYTHONUNBUFFERED. These help ensure Python modules are discoverable and output is unbuffered for real-time logging.

predict_origin

Predicts the origin for a single name and returns a JSON object with country predictions and probabilities.

batch_predict

Predicts origins for a list of names, returning predictions for each input name in a consolidated structure.