assemblyai-mcp

AssemblyAI API용 MCP 서버입니다. 전사, 자막, 화자 분리, 단어 검색, LeMUR을 에이전트가 호출할 수 있는 도구로 제공합니다.

필요해서 만들었는데 기존에 없어서 직접 작성했습니다.

설치

npm install -g assemblyai-mcp

Claude Code:

claude mcp add assemblyai -e ASSEMBLYAI_API_KEY=your-key -- npx -y assemblyai-mcp

stdio로 MCP를 지원하는 다른 모든 도구:

{
  "mcpServers": {
    "assemblyai": {
      "command": "npx",
      "args": ["-y", "assemblyai-mcp"],
      "env": { "ASSEMBLYAI_API_KEY": "your-key" }
    }
  }
}

키는 대시보드에서 받을 수 있습니다.

도구

알아두면 좋은 세 가지 결정 사항

transcribe는 기다립니다. 작업 ID와 queued 상태를 받은 에이전트는 폴링 루프를 직접 만들어야 하는데, 대개 잘못된 루프를 만듭니다. 고정 간격, 상한 없음, 포기할 때 메시지 없음. 호출자가 원한 것은 기다리는 것입니다. 실제로 ID를 원한다면 wait: false를 전달하세요. 타임아웃 시 오류 메시지는 전사 결과가 유실되지 않았음을 알리고, 이를 가져올 도구를 안내합니다.

긴 출력은 상한을 두고 그 사실을 알립니다. 전사 결과는 수백 킬로바이트에 달합니다. 전체를 반환하는 도구는 에이전트가 어차피 요약할 텍스트에 컨텍스트 창을 소모합니다. 길어질 수 있는 모든 것은 제한을 받고, 조용히 잘라내는 대신 얼마나 잘렸는지 보고합니다.

밀리초가 초가 됩니다. API는 밀리초 단위를 사용하는데, 이는 API에는 적합하지만 사람이 읽을 답변을 작성하는 모델에는 적합하지 않습니다. 타임스탬프는 소수점 한 자리 초 단위로 출력됩니다.

개발

npm install
npm run build
npm test

API 클라이언트(src/api.ts)는 MCP에 대해 알지 못하며 주입된 fetch를 사용하므로, 테스트는 네트워크와 키 없이 스크립트된 전송 계층에서 실행됩니다. 테스트는 얇은 API 래퍼에서 흔히 깨지는 부분을 다룹니다: 키가 URL에 전달되지 않는 경우, 악성 ID가 경로를 변형하지 못하도록 ID가 이스케이프되는 경우, JSON이 아닌 응답(자막은 텍스트로 도착), 오류 본문이 상태 코드만이 아닌 API가 작성한 문장을 표시하는 경우, 그리고 폴링 루프가 completed와 error 모두에서 중단되는 경우입니다.

AssemblyAI에 드리는 말씀

이 중 유용한 것이 있다면 가져가세요. MIT 라이선스이며, 포크하거나 이름을 바꾸거나 흡수하거나 버리는 것은 모두 여러분의 몫입니다. 자사 서버로 두는 것을 선호한다면, 그렇게 되도록 기꺼이 돕겠습니다.

MIT.