碳语音MCP服务器
用于集成的模型上下文协议(MCP)服务器实现 Carbon Voice的API,为人工智能助手提供语音消息、对话和工作空间管理的综合工具。
碳音: https://getcarbon.app
API: https://api.carbonvoice.app/docs
特性
- 消息管理:创建、列出和检索语音消息、对话消息和直接消息
- 用户操作:搜索和检索用户信息
- 会话管理:访问和管理对话及其参与者
- 文件夹操作:创建、组织、移动和管理文件夹及其内容
- 工作区管理:获取工作区信息
- AI行动:运行AI提示并检索AI生成的响应
- 附件支持:向邮件添加链接附件
安全与合规
此服务器完全符合 MCP安全最佳实践:
- OAuth 2.1身份验证:通过适当的令牌处理确保授权流的安全
- HTTPS强制:通过HTTPS服务的所有远程端点
- 会话安全:加密安全会话管理
- 输入验证:全面验证所有用户输入
- 速率限制:内置防滥用保护
出于安全考虑,请联系:devsupport@phononx.com
先决条件
用于标准运输(本地安装)
必修的:
- Carbon Voice API密钥 -联系Carbon Voice开发团队,索取您的API密钥:
- 📧 联系: devsupport@phononx.com
- 📧 主题:“请求MCP服务器的API密钥”
- npx安装 -你一定有
npx安装在您的系统上。npx与Node.js(14.8.0或更高版本)捆绑在一起。如果你没有安装Node.js,你可以从以下网址下载 nodejs.org.
要验证您的安装,请运行:```bash
npx --version
### 用于HTTP传输(远程)
**必修的:**
1. **没有什么** -不需要额外的先决条件。HTTP传输版本完全在云中运行,并使用OAuth2身份验证,因此不需要安装API密钥或npx。
## 配置
### 快速概览
|客户端|HTTP传输(远程)|Stdio传输(本地)|
| ------------------ | ----------------------- | ----------------------- |
| **光标** | ✅ 推荐|✅ 可用|
| **克劳德桌面** | ✅ 推荐|✅ 可用|
_建议使用HTTP传输,以便于设置和增强安全性。_
### 对于光标
#### HTTP传输(远程)
1. 打开的游标
1. 首选 **光标设置** > **特性** > **模型上下文协议**
1. 添加新的MCP服务器配置:```json
{
"mcpServers": {
"Carbon Voice": {
"url": "https://mcp.carbonvoice.app"
}
}
}
- 保存并重新启动游标
第一次使用它时,Cursor将引导您完成OAuth2身份验证过程。
标准运输(本地安装)
如果您更喜欢使用API密钥验证在本地运行MCP服务器:
- 打开的游标
- 首选 光标设置 > 特性 > 模型上下文协议
- 添加新的MCP服务器配置:```json
{
"mcpServers": {
"Carbon Voice": {
"command": "npx",
"env": {
"CARBON_VOICE_API_KEY": "your_api_key_here"
},
"args": ["-y", "@carbonvoice/cv-mcp-server"]
}
}
}
4. 替换 `"your_api_key_here"` 使用您实际的Carbon Voice API密钥
1. 保存并重新启动游标
### 适用于克劳德桌面
#### HTTP传输(远程)
在Claude Desktop中设置Carbon Voice非常简单!操作方法如下:
1. **打开克劳德桌面** 并导航到 **搜索和工具**
1. **转到管理连接器** 然后单击 **“添加自定义连接器”**
1. **填写连接器详细信息**:
- **名字**:给它起一个友好的名字,比如“碳之声”
- **远程MCP服务器URL**:输入 `https://mcp.carbonvoice.app`
1. **保存连接器**
1. **单击连接**:
第一次使用它时,Claude将指导您完成OAuth2身份验证过程。您只需使用您的Carbon Voice帐户登录并授予权限。在那之后,你就准备好了!
#### 标准运输(本地安装)
如果您更喜欢使用API密钥验证在本地运行MCP服务器:
1. 打开您的Claude Desktop配置文件:
- **macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`
- **视窗**: `%APPDATA%\Claude\claude_desktop_config.json`
1. 添加Carbon Voice MCP服务器配置:```json
{
"mcpServers": {
"Carbon-Voice": {
"command": "npx",
"env": {
"CARBON_VOICE_API_KEY": "your_api_key_here"
},
"args": ["-y", "@carbonvoice/cv-mcp-server"]
}
}
}
- 替换
"your_api_key_here"使用您实际的Carbon Voice API密钥 - 保存文件并重新启动Claude Desktop
环境变量(仅适用于Stdio版本)
使用MCP服务器的stdio版本时,您可以配置其他环境变量:
LOG_LEVEL
控制日志输出的详细程度。可用选项:
info(默认)-标准日志记录信息debug-最详细的日志记录,显示详细的请求/响应数据warn-只有警告和错误消息error-只有错误消息
例子:```json
{
"mcpServers": {
"Carbon-Voice": {
"command": "npx",
"env": {
"CARBON_VOICE_API_KEY": "your_api_key_here",
"LOG_LEVEL": "debug"
},
"args": ["-y", "@carbonvoice/cv-mcp-server"]
}
}
}
#### LOG_DIR
指定存储日志文件的目录。默认值为: `/tmp/cv-mcp-server/logs`
服务器将在此目录中创建两个日志文件:
- `combined.log` -包含所有日志消息
- `error.log` -仅包含错误消息
**例子:**```json
{
"mcpServers": {
"Carbon-Voice": {
"command": "npx",
"env": {
"CARBON_VOICE_API_KEY": "your_api_key_here",
"LOG_DIR": "/Users/USER_NAME/Documents/cv-mcp-server/logs"
},
"args": ["-y", "@carbonvoice/cv-mcp-server"]
}
}
}
包含两个变量的完整示例:```json
{
"mcpServers": {
"Carbon-Voice": {
"command": "npx",
"env": {
"CARBON_VOICE_API_KEY": "your_api_key_here",
"LOG_LEVEL": "debug",
"LOG_DIR": "/Users/USER_NAME/Documents/cv-mcp-server/logs"
},
"args": ["-y", "@carbonvoice/cv-mcp-server"]
}
}
}
## 可用工具
### 消息
- **`list_messages`** -列出带有日期筛选的邮件(最大31天范围)
- **`get_message`** -按ID检索特定邮件
- **`get_recent_messages`** -获取10条最新消息的完整上下文
- **`create_conversation_message`** -向对话发送消息
- **`create_direct_message`** -向用户或组发送直接消息
- **`create_voicememo_message`** -创建语音备忘录消息
- **`add_attachments_to_message`** -向现有邮件添加链接附件
### 用户
- **`get_user`** -按ID检索用户信息
- **`search_user`** -通过电话号码或电子邮件查找用户
- **`search_users`** -通过各种标识符搜索多个用户
### 交谈
- **`list_conversations`** -获取过去6个月的所有对话
- **`get_conversation`** -按ID检索对话详细信息
- **`get_conversation_users`** -让所有用户参与对话
### 文件夹
- **`get_workspace_folders_and_message_counts`** -获取文件夹和邮件统计信息
- **`get_root_folders`** -列出工作区的根文件夹
- **`create_folder`** -创建新文件夹
- **`get_folder`** -检索文件夹信息
- **`get_folder_with_messages`** -获取包含邮件的文件夹
- **`update_folder_name`** -重命名文件夹
- **`delete_folder`** -删除文件夹(⚠️ 破坏性操作)
- **`move_folder`** -在不同位置之间移动文件夹
- **`move_message_to_folder`** -将邮件组织到文件夹中
### 工作区
- **`get_workspaces_basic_info`** -获取基本工作空间信息
### AI行动
- **`list_ai_actions`** -列出可用的AI提示/操作
- **`run_ai_action`** -对消息执行AI操作
- **`run_ai_action_for_shared_link`** -在共享内容上运行AI操作
- **`get_ai_action_responses`** -检索AI生成的响应
## 使用示例
### 入门指南
配置后,您可以通过AI助手与Carbon Voice进行交互。以下是一些示例请求:```
"Show me my recent messages"
"Create a voice memo about today's meeting"
"Search for user john@example.com"
"Show me my workspace information"
"List my conversations from this week"
使用文件夹```
"Create a folder called 'Project Updates'"
"Move message ID 12345 to the Project Updates folder"
"Show me all messages in the Marketing folder"
### AI行动```
"Run a summary AI action on message ID 67890"
"List all available AI prompts"
"Get AI responses for conversation ID 123"
错误处理
服务器包括全面的错误处理和日志记录。错误以结构化格式返回,其中包括:
- 错误消息
- 状态代码
- 请求上下文
- 调试信息
发展
本节面向希望贡献、实现新功能或解决问题的开发人员。
开发命令
建设与发展```bash
npm run build # Build the project
npm run auto:build # Watch mode with auto-rebuild (recommended for development)
npm run lint:fix # Fix linting issues
#### API生成```bash
npm run generate:api # Generate TypeScript types from Carbon Voice API
运行服务器```bash
npm run dev:http # Start HTTP server in development mode with hot reload
npm run start:http # Start HTTP server in production mode
#### MCP检验员测试
**设置**:复制 `.env.sample` 向 `.env` 并配置您的开发环境变量。```bash
npm run mcp:inspector:stdio # Test stdio transport with MCP Inspector
npm run mcp:inspector:http # Test HTTP transport with MCP Inspector
对于stdio传输测试:
- 使用令牌打开生成的URL(例如。,
http://localhost:6274/?MCP_PROXY_AUTH_TOKEN=46bfbd8938955be26da7f2089a8cccb7be57ed570e65d8d2d68e95561ed9b79e) - 集 传输类型:
STDIO - 集 命令:
node - 点击 连接
- 应看到已连接信息。
对于HTTP传输测试:
- 使用令牌打开生成的URL
- 集 传输类型:
Streamable HTTP - 集 统一资源定位符:
http://localhost:3005 - 单击Auth,然后单击Quick Oauth Flow。
- 将被重定向到碳语音认证页面。登录后,承载令牌应自动添加到授权请求标头中。
- 点击 连接
- 应看到已连接信息。
版本管理
备注:只有合并到主分支的代码才具有 不同版本 从当前版本开始,将创建一个新的Git标签并触发新的npm包发布。CI/CD管道会自动检查中的版本 package.json 在部署和发布之前已更改。
版本命令```bash
npm run version:patch # Bump patch version (1.0.0 → 1.0.1)
npm run version:minor # Bump minor version (1.0.0 → 1.1.0)
npm run version:major # Bump major version (1.0.0 → 2.0.0)
#### 释放命令```bash
npm run release:patch # Build, test, version patch, and merge to main
npm run release:minor # Build, test, version minor, and merge to main
npm run release:major # Build, test, version major, and merge to main
npm run deploy:release # Build, test, and merge to main (no version bump)
开发工作流程示例
致力于发展```bash
1. Make your changes and test locally
npm run build
npm run lint:fix
2. Commit and push to develop
git add .
git commit -m "feat: add new message filtering feature"
git push origin develop
#### 发布Bug修复```bash
# 1. Test your changes
npm run build
npm run mcp:inspector:http
# 2. Release patch version
npm run release:patch
发布新功能```bash
1. Test your changes
npm run build
npm run mcp:inspector:stdio
npm run mcp:inspector:http
2. Release minor version
npm run release:minor
```
开发技巧
- 使用
auto:build在文件更改时自动重建的开发过程中 - 测试两种运输方式 发布前与MCP检查员进行沟通
- 跑
generate:api当Carbon Voice API发生变化时 - 使用语义版本控制:补丁用于修复,次要用于功能,主要用于破坏性更改
- 始终进行测试 发布前同时使用stdio和HTTP传输
MCP合规性
此服务器完全符合 模型上下文协议规范 并遵循官方文件中概述的所有安全最佳实践。该实现支持MCP规范中定义的stdio和HTTP传输。
支持
- 问题: GitHub问题
- API密钥请求: devsupport@phononx.com
- 碳语音平台: https://getcarbon.app
- API文档: https://api.carbonvoice.app/docs
许可证
ISC许可证-请参阅 许可证 文件以获取详细信息。
备注:此MCP服务器需要有效的Carbon Voice API密钥才能使用stdio传输。对于HTTP传输,OAuth2身份验证是通过web界面自动处理的。在尝试使用服务器之前,请确保您拥有适当的凭据。
