namegen-mcp

An MCP server that mirrors the behaviour of https://names.ironarachne.com, backed by the @ironarachne/made-up-names dataset. It exposes a single tool, generate-names, which accepts race, type, and number arguments to return randomly generated names. The defaults match the hosted API (race defaults to human, number defaults to 1).

Prerequisites

• Node.js 18 or newer
• npm 9 or newer (ships with recent Node.js distributions)

Installation

npm install

This downloads the MCP SDK and the name generation dataset locally so the server operates without any external network calls.

Running the server

Development (hot reload)

npm run dev

tsx compiles the TypeScript entry point in-memory and wires the server to stdio, which is the transport expected by most MCP-compatible clients.

Production build

npm run build
npm start

This emits the compiled files into dist/ and runs the stdio server from the generated JavaScript.

Using with Claude Desktop (and other MCP frontends)

1. Open Claude Desktop and navigate to Settings → Developer → Model Context Protocol.

2. Add a new MCP server entry with one of the following command setups (update cwd to wherever you cloned the repo). Claude’s configuration expects servers inside a mcpServers object, so the full JSON looks like this:

   {
     "mcpServers": {
       "namegen": {
         "command": "npm",
         "args": ["start"],
         "cwd": "/absolute/path/to/namegen-mcp"
       }
     }
   }
   

   To run the TypeScript entry without a prior build, swap the command block for the following:

   {
     "mcpServers": {
       "namegen": {
         "command": "npx",
         "args": ["tsx", "src/server.ts"],
         "cwd": "/absolute/path/to/namegen-mcp"
       }
     }
   }
   

   Important: Set cwd to the project root (the folder containing package.json). Pointing it at dist/ or another subdirectory will make npm fail to locate the scripts file and the server exits with code 1. If you use the Settings UI, Claude writes this JSON for you; if you edit claude-desktop-config.json manually, be sure to keep the mcpServers wrapper or the app will report “Invalid config: missing mcpServers object.”

3. For the npm start variant, run npm run build once so dist/server.js is available. The npx tsx command path does not require a pre-build.

4. Save the configuration and restart Claude Desktop if it does not immediately recognise the new server.

Any other MCP-compatible frontend that supports stdio transports can use the same command/args/cwd configuration to launch this project.

Tool reference

• Tool ID: generate-names
• Parameters:
  • race (string, optional, default "human")
  • type (string, required, one of male, female, family, given, region, town, culture)
  • number (integer, optional, default 1, maximum 50)
• Response: The tool returns a JSON payload with the canonical race, requested type, requested count, and an array of generated names. The same payload is returned as structured content and rendered text for convenience.

Two static resources are also registered:

• namegen://races – JSON list of valid race identifiers
• namegen://name-types – JSON list of valid name types

Example

Requesting three female elf names via an MCP client might return a payload like the following:

{
  "race": "elf",
  "type": "female",
  "count": 3,
  "names": [
    "Aerithain",
    "Nylenna",
    "Valesri"
  ]
}

Because all content is generated locally, the server can run offline after the initial dependency installation.

Troubleshooting

• Server exits immediately with code 1 in Claude: make sure the cwd in your MCP configuration points to the repository root (where package.json lives) and that you ran npm install. If you use the npm start command, run npm run build once so dist/server.js exists.