avatar-clone MCP server

March 10, 2025 · View on GitHub

A MCP server project

Overview

The avatar-clone MCP server helps to clone avatars on platforms like Hegen, Tavus, or custom models for avatars.

Components

Resources

The server implements a simple note storage system with:

Custom note:// URI scheme for accessing individual notes
Each note resource has a name, description, and text/plain mimetype

Prompts

The server provides a single prompt:

summarize-notes: Creates summaries of all stored notes
- Optional "style" argument to control detail level (brief/detailed)
- Generates prompt combining all current notes with style preference

Tools

The server implements one tool:

add-note: Adds a new note to the server
- Takes "name" and "content" as required string arguments
- Updates server state and notifies clients of resource changes

Configuration

[TODO: Add configuration details specific to your implementation]

Quickstart

Installation

Clone the Repository:

git clone https://github.com/Pratik-Kumar-Cse/avatar-clone-mcp.git
cd avatar-clone-mcp

Create a Virtual Environment (Recommended):

python3 -m venv .venv
source .venv/bin/activate  # Linux/macOS
.venv\Scripts\activate  # Windows

Run the Server:
```
uv run avatar-clone
```

Using uv (recommended)

When using uv no specific installation is needed. We will use uvx to directly run avatar-clone.

Using PIP

Alternatively, you can install avatar-clone via pip:

pip install avatar-clone

After installation, you can run it as a script using:

python -m avatar_clone

Configuration

Usage with Claude Desktop

On MacOS: ~/Library/Application\ Support/Claude/claude_desktop_config.json On Windows: %APPDATA%/Claude/claude_desktop_config.json

Development/Unpublished Servers Configuration

"mcpServers": {
  "avatar-clone": {
    "command": "uv",
    "args": [
      "--directory",
      "/Users/pratikkumar/Desktop/Projects/ciny/ciny-main/mcp-server/avatar-clone",
      "run",
      "avatar-clone"
    ]
  }
}

Published Servers Configuration

"mcpServers": {
  "avatar-clone": {
    "command": "uvx",
    "args": [
      "avatar-clone"
    ]
  }
}

Development

Building and Publishing

To prepare the package for distribution:

Sync dependencies and update lockfile:
```
uv sync
```
Build package distributions:
```
uv build
```

This will create source and wheel distributions in the dist/ directory.

Publish to PyPI:
```
uv publish
```

Note: You'll need to set PyPI credentials via environment variables or command flags:

Token: --token or UV_PUBLISH_TOKEN
Or username/password: --username/UV_PUBLISH_USERNAME and --password/UV_PUBLISH_PASSWORD

Usage with Claude Desktop

Add this to your claude_desktop_config.json:

Using uvx

"mcpServers": {
  "avatar-clone": {
    "command": "uvx",
    "args": ["avatar-clone", "--repository", "path/to/git/repo"]
  }
}

Using docker

Note: replace '/Users/username' with the path that you want to be accessible by this tool

"mcpServers": {
  "avatar-clone": {
    "command": "docker",
    "args": ["run", "--rm", "-i", "--mount", "type=bind,src=/Users/username,dst=/Users/username", "avatar-clone"]
  }
}

Using pip installation

"mcpServers": {
  "avatar-clone": {
    "command": "python",
    "args": ["-m", "avatar_clone", "--repository", "path/to/git/repo"]
  }
}

Usage with Zed

Add to your Zed settings.json:

Using uvx

"context_servers": [
  "avatar-clone": {
    "command": {
      "path": "uvx",
      "args": ["avatar-clone"]
    }
  }
],

Using pip installation

"context_servers": {
  "avatar-clone": {
    "command": {
      "path": "python",
      "args": ["-m", "avatar_clone"]
    }
  }
},

Debugging

Since MCP servers run over stdio, debugging can be challenging. For the best debugging experience, we strongly recommend using the MCP Inspector.

You can launch the MCP Inspector via npm with this command:

npx @modelcontextprotocol/inspector uv --directory /Users/pratikkumar/Desktop/Projects/ciny/ciny-main/mcp-server/avatar-clone run avatar-clone

Upon launching, the Inspector will display a URL that you can access in your browser to begin debugging.

Docker

{
  "mcpServers": {
    "avatar-clone": {
      "command": "docker",
      "args": [
        "run",
        "--rm",
        "-i",
        "--mount",
        "type=bind,src=/Users/username/Desktop,dst=/projects/Desktop",
        "--mount",
        "type=bind,src=/path/to/other/allowed/dir,dst=/projects/other/allowed/dir,ro",
        "--mount",
        "type=bind,src=/path/to/file.txt,dst=/projects/path/to/file.txt",
        "avatar-clone"
      ]
    }
  }
}

UVX

{
  "mcpServers": {
    "avatar-clone": {
      "command": "uv",
      "args": [
        "--directory",
        "/<path to mcp-servers>/avatar-clone",
        "run",
        "avatar-clone"
      ]
    }
  }
}

Build

Docker build:

docker build -t avatar-clone .

This MCP server is licensed under the MIT License. This means you are free to use, modify, and distribute the software, subject to the terms and conditions of the MIT License. For more details, please see the LICENSE file in the project repository.