Carbon Voice MCP Server
A Model Context Protocol (MCP) server implementation for integrating with Carbon Voice's API, providing AI assistants with comprehensive tools for voice messaging, conversations, and workspace management.
Carbon Voice: https://getcarbon.app
API: https://api.carbonvoice.app/docs
Features
- Message Management: Create, list, and retrieve voice messages, conversation messages, and direct messages
- User Operations: Search and retrieve user information
- Conversation Management: Access and manage conversations and their participants
- Folder Operations: Create, organize, move, and manage folders and their contents
- Workspace Administration: Get workspace information
- AI Actions: Run AI prompts and retrieve AI-generated responses
- Attachment Support: Add link attachments to messages
Security & Compliance
This server fully complies with MCP Security Best Practices:
- OAuth 2.1 Authentication: Secure authorization flow with proper token handling
- HTTPS Enforcement: All remote endpoints served over HTTPS
- Session Security: Cryptographically secure session management
- Input Validation: Comprehensive validation of all user inputs
- Rate Limiting: Built-in protection against abuse
For security concerns, please contact: devsupport@phononx.com
Prerequisites
For Stdio Transport (Local Installation)
Required:
- Carbon Voice API Key - Contact the Carbon Voice development team to request your API key:
- 📧 Contact: devsupport@phononx.com
- 📧 Subject: "Request API key for MCP Server"
- npx Installation - You must have
npx
installed on your system. npx comes bundled with Node.js (version 14.8.0 or later). If you don't have Node.js installed, you can download it from nodejs.org.To verify your installation, run:
For HTTP Transport (Remote)
Required:
- Nothing! - No additional prerequisites are required. The HTTP transport version runs entirely in the cloud and uses OAuth2 authentication, so you don't need an API key or npx installed.
Configuration
Quick Overview
Client | HTTP Transport (Remote) | Stdio Transport (Local) |
---|---|---|
Cursor | ✅ Recommended | ✅ Available |
Claude Desktop | ✅ Recommended | ✅ Available |
HTTP Transport is recommended for easier setup and enhanced security.
For Cursor
HTTP Transport (Remote)
- Open Cursor
- Go to Cursor Settings > Features > Model Context Protocol
- Add a new MCP server configuration:
- Save and restart Cursor
The first time you use it, Cursor will guide you through the OAuth2 authentication process.
Stdio Transport (Local Installation)
If you prefer to run the MCP server locally with API key authentication:
- Open Cursor
- Go to Cursor Settings > Features > Model Context Protocol
- Add a new MCP server configuration:
- Replace
"your_api_key_here"
with your actual Carbon Voice API key - Save and restart Cursor
For Claude Desktop
HTTP Transport (Remote)
Setting up Carbon Voice in Claude Desktop is straightforward! Here's how to do it:
- Open Claude Desktop and navigate to Search and Tools
- Go to Manage Connectors and click "Add custom connector"
- Fill in the connector details:
- Name: Give it a friendly name like "Carbon Voice"
- Remote MCP Server URL: Enter
https://mcp.carbonvoice.app
- Save your connector
- Click Connect:
The first time you use it, Claude will guide you through the OAuth2 authentication process. You'll just need to sign in with your Carbon Voice account and grant permissions. After that, you're all set!
Stdio Transport (Local Installation)
If you prefer to run the MCP server locally with API key authentication:
- Open your Claude Desktop configuration file:
- macOS:
~/Library/Application Support/Claude/claude_desktop_config.json
- Windows:
%APPDATA%\Claude\claude_desktop_config.json
- macOS:
- Add the Carbon Voice MCP server configuration:
- Replace
"your_api_key_here"
with your actual Carbon Voice API key - Save the file and restart Claude Desktop
Environment Variables (Only available for Stdio Version)
When using the stdio version of the MCP server, you can configure additional environment variables:
LOG_LEVEL
Controls the verbosity of logging output. Available options:
info
(default) - Standard logging informationdebug
- Most verbose logging, shows detailed request/response datawarn
- Only warning and error messageserror
- Only error messages
Example:
LOG_DIR
Specifies the directory where log files will be stored. Defaults to: /tmp/cv-mcp-server/logs
The server will create two log files in this directory:
combined.log
- Contains all log messageserror.log
- Contains only error messages
Example:
Complete Example with Both Variables:
Available Tools
Messages
list_messages
- List messages with date filtering (max 31-day range)get_message
- Retrieve a specific message by IDget_recent_messages
- Get the 10 most recent messages with full contextcreate_conversation_message
- Send a message to a conversationcreate_direct_message
- Send direct messages to users or groupscreate_voicememo_message
- Create voice memo messagesadd_attachments_to_message
- Add link attachments to existing messages
Users
get_user
- Retrieve user information by IDsearch_user
- Find a user by phone number or emailsearch_users
- Search multiple users by various identifiers
Conversations
list_conversations
- Get all conversations from the last 6 monthsget_conversation
- Retrieve conversation details by IDget_conversation_users
- Get all users in a conversation
Folders
get_workspace_folders_and_message_counts
- Get folder and message statisticsget_root_folders
- List root folders for a workspacecreate_folder
- Create new foldersget_folder
- Retrieve folder informationget_folder_with_messages
- Get folder with its messagesupdate_folder_name
- Rename foldersdelete_folder
- Delete folders (⚠️ destructive operation)move_folder
- Move folders between locationsmove_message_to_folder
- Organize messages into folders
Workspace
get_workspaces_basic_info
- Get basic workspace information
AI Actions
list_ai_actions
- List available AI prompts/actionsrun_ai_action
- Execute AI actions on messagesrun_ai_action_for_shared_link
- Run AI actions on shared contentget_ai_action_responses
- Retrieve AI-generated responses
Usage Examples
Getting Started
After configuration, you can interact with Carbon Voice through your AI assistant. Here are some example requests:
Working with Folders
AI Actions
Error Handling
The server includes comprehensive error handling and logging. Errors are returned in a structured format that includes:
- Error messages
- HTTP status codes
- Request context
- Debugging information
Development
This section is for developers who want to contribute, implement new features, or fix issues.
Development Commands
Building and Development
API Generation
Running the Server
Testing with MCP Inspector
Setup: Copy .env.sample
to .env
and configure your development environment variables.
For stdio transport testing:
- Open the generated URL with token (e.g.,
http://localhost:6274/?MCP_PROXY_AUTH_TOKEN=46bfbd8938955be26da7f2089a8cccb7be57ed570e65d8d2d68e95561ed9b79e
) - Set Transport Type:
STDIO
- Set Command:
node
- Click Connect
- Should see Connected info.
For HTTP transport testing:
- Open the generated URL with token
- Set Transport Type:
Streamable HTTP
- Set URL:
http://localhost:3005
- Click Auth, then Quick Oauth Flow.
- Will be redirected to Carbon Voice Auth Page. After Login, Bearer token should be auto added to Authorization Request headers.
- Click Connect
- Should see Connected info.
Version Management
Note: Only code merged to main branch with a different version from the current one will create a new Git tag and trigger a new npm package release. The CI/CD pipeline automatically checks if the version in package.json
has changed before deploying and publishing.
Version Commands
Release Commands
Development Workflow Examples
Commit to Develop
Release Bug Fix
Release New Feature
Development Tips
- Use
auto:build
during development for automatic rebuilding when files change - Test both transports with MCP Inspector before releasing
- Run
generate:api
when Carbon Voice API changes - Use semantic versioning: patch for fixes, minor for features, major for breaking changes
- Always test with both stdio and HTTP transports before releasing
MCP Compliance
This server is fully compliant with the Model Context Protocol specification and follows all security best practices outlined in the official documentation. The implementation supports both stdio and HTTP transports as defined in the MCP specification.
Support
- Issues: GitHub Issues
- API Key Requests: devsupport@phononx.com
- Carbon Voice Platform: https://getcarbon.app
- API Documentation: https://api.carbonvoice.app/docs
License
ISC License - See LICENSE file for details.
Note: This MCP server requires a valid Carbon Voice API key to function with stdio transport. For HTTP transport, OAuth2 authentication is handled automatically through the web interface. Please ensure you have the appropriate credentials before attempting to use the server.
hybrid server
The server is able to function both locally and remotely, depending on the configuration or use case.
Tools
Access your Carbon Voice conversations and voice memos—retrieving messages, conversations, voice memos, and more as well as send messages to Carbon Voice users.
Related MCP Servers
- AsecurityFlicenseAqualityProvides access to Intercom conversations and chats through the Model Context Protocol, allowing LLMs to query and analyze Intercom conversations with various filtering options.Last updated -26TypeScript
- -securityFlicense-qualityProvides text-to-speech capabilities through the Model Context Protocol, allowing applications to easily integrate speech synthesis with customizable voices, adjustable speech speed, and cross-platform audio playback support.Last updated -7Python
- -securityAlicense-qualityA macOS app that provides an MCP server to your Messages, Contacts, and moreLast updated -742MIT License
- -securityAlicense-qualityProvides voice recognition and text extraction capabilities with support for both stdio and MCP modes, processing audio files or base64 encoded data and returning structured results with language, emotion, and speaker information.Last updated -PythonMIT License