TwelveLabs MCP Server

이 프로젝트는 TwelveLabs(비디오 이해 플랫폼)와 관련이 없습니다. 이는 ElevenLabs Conversational AI API — 음성 에이전트, 지식 베이스, 대화, TTS를 위한 MCP 서버입니다. "TwelveLabs"라는 이름은 프로젝트 코드명일 뿐입니다.

향상된 MCP(Model Context Protocol) 서버로, 호환되는 모든 MCP 클라이언트가 ElevenLabs Conversational AI API에 직접 접근할 수 있게 해줍니다. 공식 ElevenLabs MCP 커넥터가 제공하지 않는 기능도 포함합니다.

다루는 내용

• 에이전트 -- 목록 조회, 전체 구성 가져오기(LLM 모델 + 온도 포함), 프롬프트/설정 업데이트, 웹훅 및 파일 업로드 관리

• 지식 베이스 -- 목록 조회, 전체 내용 읽기, 텍스트/URL 문서 추가, 문서 삭제

• 대화 -- 기록 필터링 및 태그 지정, 대화록 검사, 통화 후 분석/평가 재실행

• 음성 -- 사용 가능한 음성 목록 및 검색

Related MCP server: elevenlabs-mcp-experiments

사전 요구 사항

• Node.js >= 18

• ElevenLabs API 키 -- elevenlabs.io에서 받으세요.

빠른 시작

옵션 A: npx (클론 불필요)

ELEVENLABS_API_KEY=your-key npx twelvelabs-mcp-server

옵션 B: 클론 및 빌드

git clone https://github.com/micro-JAY/twelvelabs-mcp-server.git
cd twelvelabs-mcp-server
npm install --include=dev
npm run build

MCP 클라이언트 연결

MCP 클라이언트 구성에 동일한 서버 항목을 추가하세요. 구성 파일 위치와 주변 구문은 클라이언트에 따라 다릅니다. 다음은 표준 stdio 서버 정의입니다:

{
  "mcpServers": {
    "twelvelabs": {
      "command": "node",
      "args": ["/path/to/twelvelabs-mcp-server/dist/index.js"],
      "env": {
        "ELEVENLABS_API_KEY": "your-api-key-here"
      }
    }
  }
}

MCP 클라이언트를 다시 시작하거나 다시 연결하세요. 사용 가능한 도구 목록에 twelvelabs가 표시됩니다.

사용 방법

MCP 지원 어시스턴트에게 도구를 사용하도록 요청하세요. 예:

"내 에이전트 목록을 보여줘" "agent_1001kjbh14xce5kbreh55ydf4rae의 전체 구성을 가져와" "그 에이전트의 최근 대화 10개를 보여줘" "conversation_xyz의 대화록과 분석을 가져와"

호환성

이 서버는 stdio 전송을 지원하고 로컬 서버 프로세스에 대한 환경 변수를 구성할 수 있는 MCP 클라이언트와 함께 작동합니다. 원격 HTTP MCP 서버만 지원하는 클라이언트는 호환되는 stdio 브리지 또는 프록시가 필요합니다.

도구 참조

에이전트 도구

지식 베이스 도구

대화 도구

음성 도구

보안

• 입력 검증 -- 모든 도구 매개변수는 API에 도달하기 전에 Zod 스키마로 검증됩니다.

• HTTPS 강제 -- 웹훅 URL은 HTTPS만 사용하도록 검증됩니다.

• 경로 탐색 보호 -- 문서 및 에이전트 ID는 경로 탐색을 방지하기 위해 정화됩니다.

• 오류 정화 -- 내부 오류는 포착되어 안전한 MCP 오류 응답으로 반환됩니다. 원시 스택 추적은 클라이언트에 노출되지 않습니다.

개발

npm run dev   # watch mode with tsx -- auto-reloads on file changes
npm run build # compile to dist/

기여

1. 저장소를 포크하세요.

2. 기능 브랜치를 만드세요 (git checkout -b feat/my-feature)

3. 변경 사항을 커밋하세요 (git commit -m 'feat: add my feature')

4. 브랜치에 푸시하세요 (git push origin feat/my-feature)

5. Pull Request를 여세요.

라이선스

MIT -- 자세한 내용은 LICENSE를 참조하세요.

아키텍처 참고

모든 도구는 시작 시 ELEVENLABS_API_KEY로 초기화되는 단일 Axios 클라이언트 인스턴스(src/client.ts)를 공유합니다. 도구 구현은 src/tools/에 있으며, 도메인별로 하나의 파일로 구성되고 src/index.ts의 McpServer에 등록됩니다. 서버는 stdio 전송(stdin/stdout)을 통해 통신하므로 모든 디버그 로깅은 console.log가 아닌 console.error(stderr)를 사용합니다.