Metadata-Version: 2.5
Name: liveface-mcp
Version: 0.1.0
Summary: Speak as a Liveface avatar from Claude Code, Claude Desktop or Codex
Project-URL: Homepage, https://liveface.io
Author: Liveface
License: Liveface MCP Server Licence
        
        Copyright (c) 2026 Liveface (https://liveface.io). All rights reserved.
        
        This package, liveface-mcp, including its code, pages and documentation
        (the "Software"), is licensed, not sold.
        
        1. Use. You may install the Software and run it, unmodified, with AI agent
           applications to use avatars from a Liveface account, for as long as your
           use of Liveface follows Liveface's terms of service.
        
        2. Distribution. You may not copy, publish, sell, sublicense or distribute
           the Software or a modified copy of it, on its own or as part of another
           library, tool or service; point others to its published package instead.
        
        3. Restrictions. You may not modify the Software, use it or any part of it
           with a service other than Liveface, or remove this notice from it.
        
        4. Ownership. Liveface keeps all rights in the Software not expressly
           granted here.
        
        5. Termination. This licence ends automatically if you break its terms or
           your Liveface account is closed; then you must stop using the Software.
        
        6. No warranty. THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY
           KIND, EXPRESS OR IMPLIED, INCLUDING THE WARRANTIES OF MERCHANTABILITY,
           FITNESS FOR A PARTICULAR PURPOSE AND NON-INFRINGEMENT. IN NO EVENT SHALL
           LIVEFACE BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN
           AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN
           CONNECTION WITH THE SOFTWARE OR THE USE OF OR OTHER DEALINGS IN IT.
License-File: LICENSE
Keywords: avatar,claude,codex,liveface,mcp,talking-avatar
Classifier: License :: Other/Proprietary License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Topic :: Multimedia :: Video
Requires-Python: >=3.10
Requires-Dist: mcp<3,>=2
Description-Content-Type: text/markdown

# liveface-mcp: Liveface for AI agents

An MCP server for Claude Code, Claude Desktop and Codex. Inside the chat, the
**studio** lets you choose an avatar and a voice, write a line and get a video
of the avatar saying it, or make a new avatar from a photo, once you have
connected your [Liveface](https://liveface.io) account. Without an account,
shared avatars still speak in a browser window.

## Install

With [uv](https://docs.astral.sh/uv/) nothing needs installing first. In
Claude Code:

```sh
claude mcp add liveface -- uvx liveface-mcp
```

or in the MCP config of Claude Desktop or Codex:

```json
{
  "mcpServers": {
    "liveface": {
      "command": "uvx",
      "args": ["liveface-mcp"],
      "env": { "LIVEFACE_CLIENT_NAME": "Claude Desktop" }
    }
  }
}
```

Or install it with `pipx install liveface-mcp` (or `pip install liveface-mcp`)
and use the `liveface-mcp` command. Python 3.10 or later.

## Connecting your account

Ask for the studio and press **Connect your account** (or, in a terminal,
ask the agent to `connect_account`). A page of the dashboard opens with a code;
sign in as usual, check the code is the one the app shows, and press
**Approve**. That is the device sign-in of `docs/connected-apps.md`: the app
never sees your password, gets a session limited to avatars, their creation
and speech (never members, keys, deleting, or settings), keeps it in
`~/.liveface/mcp-credentials.json` (readable by you only), and is cut off at
once when you disconnect it in the dashboard's Settings, under Connected apps.

## Configuration

| Variable | Meaning |
|---|---|
| `LIVEFACE_BASE` | The site. Default `https://liveface.io`. |
| `LIVEFACE_CLIENT_NAME` | How this app names itself when asking to connect. |
| `LIVEFACE_CREDENTIALS` | Where the session is kept. Default `~/.liveface/mcp-credentials.json`. |
| `LIVEFACE_AVATARS` | Shared avatars, no account needed: `name=token` pairs (a share link's token). |

## The studio (an MCP app)

`avatar_studio()` returns a page the host draws inside the chat
(`ui://liveface/studio.html`, `text/html;profile=mcp-app`):

- **Library.** Your avatars as cards (and the shared ones), a voice (every
  server voice, grouped by provider), the line (`[happy]`, `[sad]`... tags
  change the face), **Create video**: the page runs the avatar engine, has the
  avatar say it and records picture and voice into an MP4 (WebM where the
  browser writes nothing else) to play or download. A browser voice cannot be
  recorded, so an avatar on one is said in a server voice, and the page says
  which.
- **New avatar.** A person (woman, man) or an animal, the photo, the style
  (the dashboard's own pictures), the pose, the image service, the voice
  (one that suits the person), a name, and the agreements in the dashboard's
  own words. The wizard's steps run on this server (`creation.py`), with
  progress; the new avatar is then chosen in the library. When its face's
  points cannot be found (the dashboard has the person place them by hand),
  the picture is made once more, then **Finish in the dashboard** opens the
  wizard where the avatar is waiting.
- The page holds no account token: it asks this server through the host, and
  the server calls the site. Its CSP lets it reach the site only.
- It needs a host that draws MCP apps. Elsewhere the tools still answer in
  text, and `speak` opens its browser window.

## Tools

The model's: `avatar_studio`, `connect_account`, `account_status`,
`disconnect_account`, `list_avatars`, `speak(text, avatar)`, `stop`.
The page's own (hidden from the model): `studio_*`.

## Licence

Proprietary: free to use with your own Liveface account. See the `LICENSE`
file in the package.
