ElevenLabs

[!WARNING] Máy chủ MCP cục bộ này đã không còn được dùng nữa, thay thế bằng máy chủ MCP được lưu trữ bởi ElevenLabs.

Máy chủ được lưu trữ có sẵn tại https://api.elevenlabs.io/v1/mcp, không cần cài đặt hoặc chạy cục bộ. Nó xác thực bằng OAuth, vì vậy không cần sao chép khóa API vào máy khách của bạn. Xem tài liệu máy chủ MCP được lưu trữ để kết nối từ Claude, Cursor hoặc bất kỳ máy khách MCP nào khác.

Kho lưu trữ này không còn được bảo trì tích cực.

Máy chủ Model Context Protocol (MCP) chính thức của ElevenLabs cho phép tương tác với các API xử lý âm thanh và chuyển văn bản thành giọng nói mạnh mẽ. Máy chủ này cho phép các máy khách MCP như Claude Desktop, Cursor, Windsurf, OpenAI Agents và các máy khách khác tạo giọng nói, nhân bản giọng nói, phiên âm âm thanh, v.v.

Bắt đầu nhanh với Claude Desktop

1. Lấy khóa API của bạn từ ElevenLabs. Có gói miễn phí với 10k tín dụng mỗi tháng.
2. Cài đặt uv (trình quản lý gói Python), cài đặt bằng curl -LsSf https://astral.sh/uv/install.sh | sh hoặc xem uv kho lưu trữ để biết thêm các phương pháp cài đặt khác.
3. Đi tới Claude > Cài đặt > Nhà phát triển > Chỉnh sửa cấu hình > claude_desktop_config.json để bao gồm nội dung sau:

{
  "mcpServers": {
    "ElevenLabs": {
      "command": "uvx",
      "args": ["elevenlabs-mcp"],
      "env": {
        "ELEVENLABS_API_KEY": "<insert-your-api-key-here>"
      }
    }
  }
}

Nếu bạn đang sử dụng Windows, bạn sẽ phải bật "Chế độ nhà phát triển" trong Claude Desktop để sử dụng máy chủ MCP. Nhấp vào "Trợ giúp" trong menu hamburger ở góc trên bên trái và chọn "Bật Chế độ nhà phát triển".

Các máy khách MCP khác

Đối với các máy khách khác như Cursor và Windsurf, hãy chạy:

1. pip install elevenlabs-mcp
2. python -m elevenlabs_mcp --api-key={{PUT_YOUR_API_KEY_HERE}} --print để lấy cấu hình. Dán nó vào thư mục cấu hình thích hợp do máy khách MCP của bạn chỉ định.

Vậy là xong. Máy khách MCP của bạn giờ có thể tương tác với ElevenLabs thông qua các công cụ sau:

Ví dụ sử dụng

⚠️ Cảnh báo: Cần có tín dụng ElevenLabs để sử dụng các công cụ này.

Hãy thử hỏi Claude:

• "Tạo một trợ lý AI nói như thám tử phim đen trắng và có thể trả lời các câu hỏi về phim kinh điển"
• "Tạo ba biến thể giọng nói cho một nhân vật rồng cổ đại khôn ngoan, sau đó tôi sẽ chọn giọng nói yêu thích của mình để thêm vào thư viện giọng nói"
• "Chuyển đổi bản ghi âm giọng nói của tôi thành giọng hiệp sĩ thời trung cổ"
• "Tạo cảnh âm thanh của một cơn giông trong khu rừng rậm với động vật phản ứng với thời tiết"
• "Chuyển lời nói này thành văn bản, xác định các người nói khác nhau, sau đó chuyển đổi lại bằng giọng nói độc đáo cho từng người"

Các tính năng tùy chọn

Cấu hình đầu ra tệp

Bạn có thể cấu hình cách máy chủ MCP xử lý đầu ra tệp bằng các biến môi trường sau trong claude_desktop_config.json của bạn:

• ELEVENLABS_MCP_BASE_PATH: Chỉ định đường dẫn cơ sở cho các thao tác tệp (mặc định: ~/Desktop). Thư mục này cũng là ranh giới bảo mật cho các tệp đầu vào: bất kỳ đường dẫn nào được truyền cho một công cụ đọc tệp cục bộ (ví dụ: speech_to_text, isolate_audio, speech_to_speech, video_to_music, upload_music_for_inpainting) phải phân giải bên trong thư mục này, dù được cung cấp dưới dạng đường dẫn tuyệt đối hay tương đối. Các đường dẫn bên ngoài nó — ngay cả khi tuyệt đối và trước đây được chấp nhận — sẽ bị từ chối. Đặt giá trị này thành một thư mục chứa mọi thứ bạn cần đọc hoặc ghi.
• ELEVENLABS_MCP_OUTPUT_MODE: Kiểm soát cách các tệp được tạo được trả về (mặc định: files)

Các chế độ đầu ra

Biến môi trường ELEVENLABS_MCP_OUTPUT_MODE hỗ trợ ba chế độ:

1. files (mặc định): Lưu tệp vào đĩa và trả về đường dẫn tệp

   "env": {
     "ELEVENLABS_API_KEY": "your-api-key",
     "ELEVENLABS_MCP_OUTPUT_MODE": "files"
   }
   

2. resources: Trả về tệp dưới dạng tài nguyên MCP; dữ liệu nhị phân được mã hóa base64, văn bản được trả về dưới dạng văn bản UTF-8

   "env": {
     "ELEVENLABS_API_KEY": "your-api-key",
     "ELEVENLABS_MCP_OUTPUT_MODE": "resources"
   }
   

3. both: Lưu tệp vào đĩa VÀ trả về dưới dạng tài nguyên MCP

   "env": {
     "ELEVENLABS_API_KEY": "your-api-key",
     "ELEVENLABS_MCP_OUTPUT_MODE": "both"
   }
   

Lợi ích của Chế độ tài nguyên:

• Tệp được trả về trực tiếp trong phản hồi MCP dưới dạng dữ liệu mã hóa base64
• Không cần I/O đĩa - hữu ích cho môi trường container hóa hoặc không có máy chủ
• Máy khách MCP có thể truy cập nội dung tệp ngay lập tức mà không cần truy cập hệ thống tệp
• Trong chế độ both, tài nguyên có thể được tìm nạp sau bằng mẫu URI elevenlabs://filename

Các trường hợp sử dụng:

• files: Quy trình làm việc truyền thống dựa trên tệp, phát triển cục bộ
• resources: Môi trường đám mây, máy khách MCP không có quyền truy cập hệ thống tệp
• both: Tính linh hoạt tối đa, bộ nhớ đệm và các tình huống chia sẻ tài nguyên

Khóa vùng dữ liệu

Bạn có thể chỉ định vùng dữ liệu bằng biến môi trường ELEVENLABS_API_RESIDENCY. Mặc định là "us".

Lưu ý: Vùng dữ liệu chỉ là tính năng dành cho doanh nghiệp. Xem tài liệu để biết thêm chi tiết.

Đóng góp

Nếu bạn muốn đóng góp hoặc chạy từ mã nguồn:

1. Sao chép kho lưu trữ:

git clone https://github.com/elevenlabs/elevenlabs-mcp
cd elevenlabs-mcp

2. Tạo môi trường ảo và cài đặt các phụ thuộc bằng uv:

uv venv
source .venv/bin/activate
uv pip install -e ".[dev]"

3. Sao chép .env.example thành .env và thêm khóa API ElevenLabs của bạn:

cp .env.example .env
# Edit .env and add your API key

4. Chạy các bài kiểm tra để đảm bảo mọi thứ hoạt động:

./scripts/test.sh
# Or with options
./scripts/test.sh --verbose --fail-fast

5. Cài đặt máy chủ trong Claude Desktop: mcp install elevenlabs_mcp/server.py

6. Gỡ lỗi và kiểm tra cục bộ với MCP Inspector: mcp dev elevenlabs_mcp/server.py

Khắc phục sự cố

Nhật ký khi chạy với Claude Desktop có thể được tìm thấy tại:

• Windows: %APPDATA%\Claude\logs\mcp-server-elevenlabs.log
• macOS: ~/Library/Logs/Claude/mcp-server-elevenlabs.log

Hết thời gian khi sử dụng một số công cụ

Một số thao tác API ElevenLabs, như thiết kế giọng nói và cách ly âm thanh, có thể mất nhiều thời gian để hoàn tất. Khi sử dụng trình kiểm tra MCP ở chế độ phát triển, bạn có thể gặp lỗi hết thời gian mặc dù công cụ đã hoàn thành nhiệm vụ dự kiến.

Điều này không nên xảy ra khi sử dụng máy khách như Claude.

MCP ElevenLabs: spawn uvx ENOENT

Nếu bạn gặp lỗi "MCP ElevenLabs: spawn uvx ENOENT", hãy xác nhận đường dẫn tuyệt đối của nó bằng cách chạy lệnh này trong thiết bị đầu cuối của bạn:

which uvx

Khi bạn có được đường dẫn tuyệt đối (ví dụ: /usr/local/bin/uvx), hãy cập nhật cấu hình của bạn để sử dụng đường dẫn đó (ví dụ: "command": "/usr/local/bin/uvx"). Điều này đảm bảo rằng tệp thực thi chính xác được tham chiếu.