cv

This MCP server implementation provides a bridge to Carbon Voice's API, exposing a comprehensive set of MCP endpoints for managing voice messages, conversations, users, folders, and workspaces, along with AI-driven actions and attachments. The server is designed to work with MCP-compliant clients and tools (such as Cursor and Claude Desktop) via either a remote HTTP transport or a local Stdio transport. Clients can list, create, retrieve, and organize messages and conversations, search for users, and leverage AI prompts to generate responses or perform actions within conversations. The available tools include operations to list, get, and create messages; manage users and conversations; organize folder structures; and run AI actions or attach links to messages. When used with the Stdio transport, you authenticate by providing a Carbon Voice API key in the MCP server configuration, while the HTTP transport (remote) relies on OAuth2 via the cloud, with no API key required locally.

To get started, configure an MCP client to point at either the remote MCP server URL or run the local Stdio server via npx. For local operation with an API key, set the CARBON_VOICE_API_KEY environment variable in your MCP client configuration alongside the command and arguments, then start the server. Once running, you can connect your MCP clients (Cursor or Claude Desktop) and select the Carbon Voice MCP configuration to begin authenticating and using the feature set described in the README.

Prerequisites

• Node.js (version 14.8.0 or later) with npm/npx available
• Optional: Carbon Voice API key for local Stdio installation

Installation steps (local Stdio transport)

1. Ensure Node.js and npm are installed

   • Check versions:
     • node -v
     • npm -v

2. Verify npx is available (comes with Node.js):

   • npx --version

3. Run the MCP server using npx (no global install required):

   • npx -y @carbonvoice/cv-mcp-server

   This will start the local MCP server you can connect to via Cursor or Claude Desktop by configuring the MCP server under the Stdio transport.

4. (Optional) If you want to run with an API key in the environment for local usage, set the environment variable when launching the command, e.g.:

   • CARBON_VOICE_API_KEY=your_api_key_here npx -y @carbonvoice/cv-mcp-server

Configuration snippets for clients (as used in Cursor or Claude Desktop) are shown in the README under the Stdio Transport section.

Tips and notes:

• For local development, provide CARBON_VOICE_API_KEY in your MCP client configuration when using the Stdio transport. Do not expose the API key in insecure places.
• The HTTP transport (remote) runs in the cloud and uses OAuth2; no API key is needed for remote usage.
• If you enable verbose logging, consider setting LOG_LEVEL to debug to troubleshoot requests and responses during integration.
• LOG_DIR can be set to a specific path to store combined.log and error.log for easier log management when running the Stdio version.
• The available tools (messages, users, conversations, folders, workspace admin, AI actions, attachments) cover common workflow scenarios: creating and listing messages, managing participants, and leveraging AI prompts to generate or respond within conversations.
• When using Cursor or Claude Desktop with the Stdio setup, you typically configure the MCP server using the example JSON blocks in the README, substituting your API key and any desired env vars.
• If you encounter authentication issues, ensure the OAuth2 workflow is properly completed for the HTTP remote transport, or verify the API key is correctly passed in the Stdio transport configuration.