Face Generator MCP server

This face generator MCP server provides a convenient way to generate realistic human face images using thispersondoesnotexist.com. It allows applications like Cline to request and generate human faces on demand through the Model Context Protocol (MCP).

Prerequisites

Before getting started, make sure you have:

• Node.js and npm: Install the LTS version from nodejs.org

Verify your installation by running:

node -v
npm -v

Both commands should display version numbers, confirming successful installation.

Installation and Setup

Follow these steps to install and set up the MCP server:

1. Clone the Repository:

   git clone https://github.com/Moe/mcp-face-generator
   cd mcp-face-generator
   

2. Install Dependencies:

   npm install
   

3. Build the Project:

   npm run build
   

Running the Server

You can run the server in two different modes:

Standalone Mode

Run the server directly with:

npm run start

The server will start and listen for connections from MCP clients.

Development/Debug Mode

Start the server with the MCP Inspector for debugging:

npm run dev

This will output a URL (typically http://localhost:5173) that you can open in your browser to access the MCP Inspector.

Integrating with Cline

To connect the face generator server to the Cline VS Code extension:

1. Install the Cline extension in VS Code if you haven't already.

2. Open Cline Settings:

   • Go to File → Preferences → Settings (or press Ctrl+,)
   • Search for "Cline MCP Settings"
   • Click "Edit in settings.json"

3. Add Server Configuration to the cline_mcp_settings.json file:

   {
     "mcpServers": {
       "face-generator": {
         "command": "node",
         "args": [
           "C:/PATH_TO/mcp-face-generator/build/index.js"
         ],
         "disabled": false,
         "autoApprove": []
       }
     }
   }
   

   Replace C:/PATH_TO/mcp-face-generator/build/index.js with the actual path to the index.js file in your project directory.

4. Test the Connection: Cline should automatically connect to the server and display it in the "MCP Servers" panel.

Troubleshooting

• Node.js or npm not found: Reinstall Node.js and ensure it's added to your system PATH.
• npm install fails: Check your internet connection, try deleting the node_modules folder and reinstalling, or configure proxy settings if needed.
• Cline doesn't connect: Verify the path in settings.json, ensure the server is running, and try restarting VS Code.

Tool Parameters

The generate_face tool accepts these parameters:

• outputDir (required): Directory to save the images
• fileName (optional): Custom file name (defaults to timestamp)
• count (optional): Number of images to generate (default: 1)
• width (optional): Image width in pixels (default: 256)
• height (optional): Image height in pixels (default: 256)
• shape (optional): Image shape (square|circle|rounded, default: square)
• borderRadius (optional): Border radius for rounded shape (default: 32)
• returnImageContent (optional): Return image as base64 encoded content instead of file path (default: false)

Example Usage

{
  "outputDir": "./output",
  "count": 3,
  "width": 512,
  "height": 512,
  "shape": "circle",
  "returnImageContent": true
}

How to install this MCP server

For Claude Code

To add this MCP server to Claude Code, run this command in your terminal:

claude mcp add-json "face-generator" '{"command":"npx","args":["face-generator"]}'

See the official Claude Code MCP documentation for more details.

For Cursor

There are two ways to add an MCP server to Cursor. The most common way is to add the server globally in the ~/.cursor/mcp.json file so that it is available in all of your projects.

If you only need the server in a single project, you can add it to the project instead by creating or adding it to the .cursor/mcp.json file.

Adding an MCP server to Cursor globally

To add a global MCP server go to Cursor Settings > Tools & Integrations and click "New MCP Server".

When you click that button the ~/.cursor/mcp.json file will be opened and you can add your server like this:

{
    "mcpServers": {
        "face-generator": {
            "command": "npx",
            "args": [
                "face-generator"
            ]
        }
    }
}

Adding an MCP server to a project

To add an MCP server to a project you can create a new .cursor/mcp.json file or add it to the existing one. This will look exactly the same as the global MCP server example above.

How to use the MCP server

Once the server is installed, you might need to head back to Settings > MCP and click the refresh button.

The Cursor agent will then be able to see the available tools the added MCP server has available and will call them when it needs to.

You can also explicitly ask the agent to use the tool by mentioning the tool name and describing what the function does.

For Claude Desktop

To add this MCP server to Claude Desktop:

1. Find your configuration file:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows: %APPDATA%\Claude\claude_desktop_config.json
• Linux: ~/.config/Claude/claude_desktop_config.json

2. Add this to your configuration file:

{
    "mcpServers": {
        "face-generator": {
            "command": "npx",
            "args": [
                "face-generator"
            ]
        }
    }
}

3. Restart Claude Desktop for the changes to take effect