convai-mcp-server

MCP server for Convai — create and manage AI characters from Claude in real-time.

Prerequisites

• Node.js 18 or higher
• A Convai account and API key

Install

cd convai-mcp-server
npm install

Setup

1. Copy the example env file:

   cp .env.example .env

2. Open .env and replace the placeholder with your real API key:

   CONVAI_API_KEY=your_actual_key_here

Register in Claude Desktop

Add the following block to your Claude Desktop config file:

Path: ~/Library/Application Support/Claude/claude_desktop_config.json

{
  "mcpServers": {
    "convai": {
      "command": "node",
      "args": ["/absolute/path/to/convai-mcp-server/index.js"],
      "env": {
        "CONVAI_API_KEY": "your_actual_key_here"
      }
    }
  }
}

Replace /absolute/path/to/convai-mcp-server with the real path on your machine. Alternatively, omit the env block if you have a .env file in the project directory.

Restart Claude Desktop after saving the config.

Available Tools

| Tool | What it does | Required inputs | |---|---|---| | create_character | Create a new Convai AI character | name, backstory | | get_character | Fetch full details for a character | character_id | | update_character | Update name, backstory, or voice on an existing character | character_id | | list_characters | List all characters in your account | (none) | | delete_character | Permanently delete a character | character_id | | add_knowledge | Add a knowledge entry to a character's knowledge bank | character_id, knowledge_text | | list_knowledge | List all knowledge entries for a character | character_id | | set_narrative_design | Apply structured narrative design (role, emotions, speaking style, expertise) | character_id | | clone_character | Clone an existing character into a new one, optionally with a different backstory | source_character_id, new_name |

Example Prompts

Once connected to Claude Desktop, try:

• "Create a wise elven librarian character named Sylara with a female voice who speaks in archaic formal english"

• "Add knowledge about the Forbidden Archives to Sylara"

• "Clone Sylara into a new character called The Shadow Librarian with a darker, more paranoid personality"

• "List all my Convai characters"

• "Set Sylara's narrative design: she's a Guide NPC, her emotional range goes from serene to desperately fearful, and her key topics are ancient manuscripts, forbidden magic, and celestial cartography"