使用说明
ElevenLabs MCP服务器
基于FastAPI的 模型上下文协议（MCP） 将ElevenLabs文本转语音作为易于使用的MCP工具公开。
此存储库允许任何兼容MCP的客户端列出语音、生成语音，并将高质量音频插入会话AI流中。它在本地或Docker中运行，完全可配置环境，并附带测试和CI就绪的linting。
1.工程概况
•将ElevenLabs的REST API连接到开源MCP生态系统。
•实施 initialize, tools/list，以及 tools/call 方法。
•安全 持有者代币 访问 /mcp 终点。
•附带生产就绪的Docker镜像和Compose堆栈。
2.架构图
Mermaid Source (click)
flowchart TD
subgraph Client
A[MCP Client] -- HTTP/JSON --> B((FastAPI))
end
subgraph Server
B -- "/mcp" --> C[MCP Router]
C -- `text_to_speech` --> D[ElevenLabs SDK]
D -- HTTPS --> E[(ElevenLabs API)]
C -- returns --> A
end
3.先决条件
| 工具 | 版本 |
|---|---|
| Python | 3.10+ |
| Docker引擎 | 24+ |
| Docker编写 | v2 |
| ElevenLabs帐户 | API密钥 |
4.快速入门
本地单班
python -m venv .venv && source .venv/bin/activate \
&& pip install -r requirements.txt \
&& uvicorn src.main:app --reload --host 0.0.0.0 --port 8080
访问 http://localhost:8080/docs Swagger用户界面。
Docker Compose
docker compose up --build
5.配置
复制并编辑模板：
cp config/.env.example .env
| 变量 | 默认值 | 描述 |
|---|---|---|
MCP_PORT |
8080 | 监听端口 |
MCP_HOST |
0.0.0.0 | 绑定地址 |
MCP_SECRET_TOKEN |
– | 不记名代币保护 /mcp |
ELEVENLABS_API_KEY |
– | 您的ElevenLabs API密钥 |
ELEVENLABS_VOICE_ID |
– | 未提供默认语音时 |
MCP_SERVER_NAME |
dans-mcp服务器 | 在中显示名称 /health |
MCP_VERSION |
1.0.0 | 广告语义版本 |
LOG_LEVEL |
信息 | 日志记录级别（调试/INFO/…） |
DATABASE_URL |
（评论） | 稍后启用持久性 |
6.本地运行（逐步）
python -m venv .venv
source .venv/bin/activate
pip install --upgrade pip
pip install -r requirements.txt
export $(grep -v "^#" .env | xargs) # load env vars
uvicorn src.main:app --reload --host "$MCP_HOST" --port "$MCP_PORT"
文件可在 http://localhost:$MCP_PORT/docs.
7.Docker部署
构建标记（&T）：
docker build -t ghcr.io/<user>/elevenlabs-mcp:latest .
推：
docker push ghcr.io/<user>/elevenlabs-mcp:latest
编写缩放片段：
services:
mcp:
image: ghcr.io/<user>/elevenlabs-mcp:latest
deploy:
replicas: 3
resources:
limits:
memory: 512m
env_file: .env
8.测试和缝合
# unit + integration tests
pytest -q --cov=src tests/
# static analysis + formatting
ruff check src tests
black --check src tests
CI在覆盖率或格式回归方面应该失败。
9.API参考（迷你版）
| 路径 | 方法 | 摘要 |
|---|---|---|
/ |
GET | 欢迎和有用的链接 |
/health |
GET | Liveness+ElevenLabs连接 |
/mcp |
POST | MCP协议入口点 |
完整的OpenAPI规范+交互式用户界面 /docs.
附加协议文件 docs/.
10.故障排除常见问题
| 症状 | 修复 |
|---|---|
401 Unauthorized 上 /mcp |
通行证 Authorization: Bearer <MCP_SECRET_TOKEN> |
503 ElevenLabs client not available |
验证 ELEVENLABS_API_KEY |
| 端口已在使用中 | 更改 MCP_PORT 或释放端口 |
| 音频文件未保存 | 确保 ./data 容器中存在且可写 |
11.贡献
看 贡献.md 用于分支策略、代码风格和问题工作流。
12.许可证和确认书
根据 MIT许可证 –参见 许可证.
多亏了 十一实验室, 快速API, 派丹蒂克, Uvicorn，以及 主控程序 社区，因为他们的伟大工具和灵感。
