Name Origin Predictor

Provides single- and batch-name origin predictions via Nationalize.io, exposed through an MCP server.

python

0

GitHub Stars

python

Language

7 months ago

First Indexed

3 months ago

Catalog Refreshed

Documentation & install

Readme and setup notes from the catalogue, plus a client-ready config you can copy for your MCP host.

Installation

Add the following to your MCP client configuration file.

Configuration

View docs

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

The Name Origin Predictor MCP Server is a Python-based service that uses an external API to predict the origin of names. It provides both single-name predictions and batch predictions that you can integrate with your MCP client workflows for fast, automated name-origin lookup.

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

Clone the project

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

Create and activate a virtual environment

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

Install dependencies

pip install httpx

Start the MCP server locally

python mcp-server.py

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.

## Available tools

### 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.