ElevenLabs MCP Server

Instructions

Args:
    agent_id (str, optional): Filter conversations by specific agent ID
    cursor (str, optional): Pagination cursor for retrieving next page of results
    call_start_before_unix (int, optional): Filter conversations that started before this Unix timestamp
    call_start_after_unix (int, optional): Filter conversations that started after this Unix timestamp
    page_size (int, optional): Number of conversations to return per page (1-100, defaults to 30)
    max_length (int, optional): Maximum character length of the response text (defaults to 10000)

Implementation Reference

• elevenlabs_mcp/server.py:757-768 (registration)

  The @mcp.tool decorator registers the 'list_conversations' tool and provides the schema via parameter descriptions in the docstring.

  @mcp.tool(
      description="""Lists agent conversations. Returns: conversation list with metadata. Use when: asked about conversation history.
  
      Args:
          agent_id (str, optional): Filter conversations by specific agent ID
          cursor (str, optional): Pagination cursor for retrieving next page of results
          call_start_before_unix (int, optional): Filter conversations that started before this Unix timestamp
          call_start_after_unix (int, optional): Filter conversations that started after this Unix timestamp
          page_size (int, optional): Number of conversations to return per page (1-100, defaults to 30)
          max_length (int, optional): Maximum character length of the response text (defaults to 10000)
      """
  )

• elevenlabs_mcp/server.py:769-829 (handler)

  The core handler function that executes the tool: fetches conversations from ElevenLabs API, formats them with metadata, handles pagination, truncates large responses if needed, and returns formatted TextContent.

  def list_conversations(
      agent_id: str | None = None,
      cursor: str | None = None,
      call_start_before_unix: int | None = None,
      call_start_after_unix: int | None = None,
      page_size: int = 30,
      max_length: int = 10000,
  ) -> TextContent:
      """List conversations with filtering options."""
      page_size = min(page_size, 100)
  
      try:
          response = client.conversational_ai.conversations.list(
              cursor=cursor,
              agent_id=agent_id,
              call_start_before_unix=call_start_before_unix,
              call_start_after_unix=call_start_after_unix,
              page_size=page_size,
          )
  
          if not response.conversations:
              return TextContent(type="text", text="No conversations found.")
  
          conv_list = []
          for conv in response.conversations:
              start_time = datetime.fromtimestamp(conv.start_time_unix_secs).strftime(
                  "%Y-%m-%d %H:%M:%S"
              )
  
              conv_info = f"""Conversation ID: {conv.conversation_id}
  Status: {conv.status}
  Agent: {conv.agent_name or 'N/A'} (ID: {conv.agent_id})
  Started: {start_time}
  Duration: {conv.call_duration_secs} seconds
  Messages: {conv.message_count}
  Call Successful: {conv.call_successful}"""
  
              conv_list.append(conv_info)
  
          formatted_list = "\n\n".join(conv_list)
  
          pagination_info = f"Showing {len(response.conversations)} conversations"
          if response.has_more:
              pagination_info += f" (more available, next cursor: {response.next_cursor})"
  
          full_text = f"{pagination_info}\n\n{formatted_list}"
  
          # Use utility to handle large text content
          result_text = handle_large_text(full_text, max_length, "conversation list")
  
          # If content was saved to file, prepend pagination info
          if result_text != full_text:
              result_text = f"{pagination_info}\n\n{result_text}"
  
          return TextContent(type="text", text=result_text)
  
      except Exception as e:
          make_error(f"Failed to list conversations: {str(e)}")
          # This line is unreachable but satisfies type checker
          return TextContent(type="text", text="")