agent-vrm-mcp

<div align="center">  # Tool List </div> <div align="center"> [](https://www.python.org/downloads/release/python-3100/) [](https://opensource.org/licenses/MIT) [](https://github.com/astral-sh/ruff) [](https://pytest.org) [](https://github.com/Sunwood-ai-labs/agent-vrm-mcp/stargazers) [](https://github.com/Sunwood-ai-labs/agent-vrm-mcp/network/members) [](https://github.com/Sunwood-ai-labs/agent-vrm-mcp/releases) [](https://github.com/Sunwood-ai-labs/agent-vrm-mcp/tags) </div> MCP Server that provides VRM avatar functionality via AgentVRM. This server enables Claude to generate speech from text and express it as a 3D avatar using the VRM avatar provided by the AgentVRM engine. --- ## Video Demo https://github.com/user-attachments/assets/ea4b736d-a326-45b0-be88-b01fff6dc3f3 ## Features - **Text-to-Speech**: Speaks the specified text with AgentVRM's VRM avatar. - **VRM Avatar Display**: The 3D VRM avatar speaks the text and expresses emotions and animations. - **Automatic Audio Playback**: Automatically plays the generated audio. - **Audio File Saving**: Saves the generated audio as a `.wav` file in the `assets` folder. ## Prerequisites - AgentVRM engine is running (locally or remotely) - Python 3.10 or higher ## Installation ### Using uv (Recommended) No special installation is required when using [`uv`](https://docs.astral.sh/uv/). Directly use [`uvx`](https://docs.astral.sh/uv/guides/tools/) to run *agent-vrm-mcp*. ## Configuration ### AgentVRM Engine This server requires the AgentVRM engine to function. The engine must be started manually. By default, it attempts to connect to `http://localhost:3001/api/speak_text`. You can specify a different URL using the `--api-url` argument. The AgentVRM engine can be downloaded and installed from the [official AgentVRM repository](https://github.com/pixiv/AgentVRM). ### Configuration for Claude Desktop Add to Claude Desktop settings: <details> <summary>Using uvx</summary> ```json { "mcpServers": { "vrm": { "command": "uvx", "args": ["agent-vrm-mcp", "--api-url=http://localhost:3001/api/speak_text"] } } } ``` </details> ## Available Tools - `speak_text` - Converts text to speech using AgentVRM and expresses it with a VRM avatar - Required arguments: - `text` (string): Text to be converted to speech - Optional arguments: - `speaker_id` (integer, default: 1): ID of the speaker to use - `speed_scale` (float, default: 1.0): Speed scale for playback - `auto_play` (boolean, default: True): Whether to play automatically after generation ## Special Features - The generated audio is automatically played using platform-specific methods: - **Windows**: Uses the default system player - **macOS**: Uses the built-in `afplay` utility - **Linux**: Tries `aplay` first, then falls back to `xdg-open` ## Project Structure - `src/agent_vrm_mcp`: [Source code](./src/agent_vrm_mcp/README.md) - `tests`: [Test code](./tests/README.md) ## Setup and Execution in Development Mode For developers, the setup and execution procedures in development mode using `uv` are summarized. ```bash # Install dependencies in project directory in development mode cd C:\Prj\agent-vrm-mcp uv sync # Install package in development mode uv pip install -e . # Run with MCP Inspector npx @modelcontextprotocol/inspector python -m agent_vrm_mcp --api-url=http://localhost:3001/api/speak_text ``` - `uv sync` synchronizes dependencies. - `uv pip install -e .` performs editable installation. - Using MCP Inspector allows you to start the `agent_vrm_mcp` server with a specified API endpoint. ## License agent-vrm-mcp is provided under the MIT License. This means you can freely use, modify, and distribute it according to the conditions of the MIT License. ## Links - GitHub: [https://github.com/Sunwood-ai-labs/agent-vrm-mcp](https://github.com/Sunwood-ai-labs/agent-vrm-mcp) - [Tag list](https://github.com/Sunwood-ai-labs/agent-vrm-mcp/tags) - PyPI: [https://pypi.org/project/agent-vrm-mcp/](https://pypi.org/project/agent-vrm-mcp/)