AI 에이전트와 MCP

droidline mcp로 Claude, ChatGPT, Cursor, VS Code, Gemini CLI 등 MCP 클라이언트가 안드로이드 폰을 보고 쓸 수 있게 합니다. 클라이언트별 설정과 좋은 결과를 얻는 요령을 다룹니다.

번역된 페이지입니다. 영어 문서와 내용이 다르면 영어 문서가 기준입니다. English

MCP(Model Context Protocol)는 AI 어시스턴트가 외부 도구를 쓰는 표준 방식입니다. droidline mcp는 MCP 서버입니다. 어시스턴트를 여기에 연결하면, 어시스턴트가 스크립트에서 쓰는 것과 같은 명령으로 폰 화면을 보고, 탭하고, 입력하고, 스크롤할 수 있습니다.

동작 방식

  • Droidline의 모든 명령은 같은 이름의 도구가 됩니다. 점이 들어간 이름은 밑줄로 바뀝니다. chrome.go는 chrome_go가 됩니다.
  • dump는 빈 속성을 뺀 간결한 화면 트리를 돌려주므로 모델이 쓰는 토큰이 줄어듭니다.
  • screenshot은 모델이 볼 수 있는 이미지를 돌려줍니다.
  • 서버는 에이전트에게 작업 방식을 알려 줍니다. dump로 화면을 보고, text, id, desc로 요소를 다루고, 요소가 없는 화면에서만 좌표를 쓰라고 안내합니다.
  • 와이파이, 모바일 데이터, 비행기 모드는 intent로 설정 화면을 연 뒤 cuts_network=true, wait=true를 준 batch로 스위치를 누르라고 안내합니다. 그래야 폰이 오프라인인 동안에도 혼자 끝까지 실행합니다.
  • droidline serve가 실행 중이 아니면 droidline mcp가 자기 프로세스 안에서 서버를 띄웁니다. 그래도 폰은 droidline pair로 한 번 페어링해 두어야 합니다.

클라이언트 설정

사용하는 어시스턴트의 탭을 고르세요. 어느 경우든 명령은 droidline mcp입니다. droidline이 PATH에 없다면 C:\\Tools\\droidline\\droidline.exe처럼 프로그램의 전체 경로를 대신 쓰세요(JSON 안에서는 백슬래시를 두 번 씁니다).

Settings, Developer, Edit Config를 차례로 열거나, 파일을 직접 고치세요.

  • Windows: %APPDATA%\Claude\claude_desktop_config.json
  • macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
{
  "mcpServers": {
    "droidline": { "command": "droidline", "args": ["mcp"] }
  }
}

Claude Desktop을 다시 시작하세요. 새 채팅의 도구 메뉴에 Droidline 도구가 나타납니다.

ChatGPT 데스크톱 앱에서 Settings, MCP servers, Add server를 차례로 여세요. 이름에 droidline을 넣고 STDIO를 고른 뒤, 명령에 droidline, 인자에 mcp를 넣고 저장한 다음 Restart를 누르세요.

ChatGPT 데스크톱 앱, Codex CLI, Codex IDE 확장은 설정 하나를 함께 씁니다. 그래서 터미널에서 추가해도 됩니다.

codex mcp add droidline -- droidline mcp

또는 ~/.codex/config.toml(Windows에서는 %USERPROFILE%\.codex\config.toml)에 직접 쓰세요.

[mcp_servers.droidline]
command = "droidline"
args = ["mcp"]

웹 브라우저의 ChatGPT는 이 로컬 설정을 읽지 않으므로, 데스크톱 앱이나 Codex를 쓰세요.

claude mcp add droidline -- droidline mcp

그런 다음 claude를 실행하고 폰을 봐 달라고 요청하세요. 서버가 연결됐는지는 claude mcp list로 확인합니다.

모든 프로젝트에서 쓰려면 ~/.cursor/mcp.json에, 한 프로젝트에서만 쓰려면 그 프로젝트 안의 .cursor/mcp.json에 다음을 추가하세요.

{
  "mcpServers": {
    "droidline": { "command": "droidline", "args": ["mcp"] }
  }
}

Cursor 설정에서 MCP를 열고 droidline이 목록에 있고 켜져 있는지 확인하세요.

워크스페이스의 .vscode/mcp.json에 다음을 추가하세요.

{
  "servers": {
    "droidline": { "type": "stdio", "command": "droidline", "args": ["mcp"] }
  }
}

그 위에 나타나는 코드 렌즈에서 서버를 시작한 뒤, Copilot의 에이전트 모드에서 도구를 쓰세요.

gemini mcp add -s user droidline droidline mcp

-s user를 붙이면 모든 프로젝트에서 쓰이고, 빼면 지금 프로젝트에만 추가됩니다. ~/.gemini/settings.json에 직접 써도 됩니다.

{
  "mcpServers": {
    "droidline": { "command": "droidline", "args": ["mcp"] }
  }
}

Gemini CLI 안에서 /mcp를 입력하면 서버가 연결됐는지와 도구 목록이 나옵니다.

AI Assistant에서 Settings, Tools, AI Assistant, **Model Context Protocol (MCP)**를 차례로 열고 Add를 누르세요. STDIO 연결을 고르고 JSON configuration에 다음을 붙여 넣으세요.

{
  "mcpServers": {
    "droidline": { "command": "droidline", "args": ["mcp"] }
  }
}

OK를 누른 다음 Apply를 누르면 서버가 시작됩니다. 연결됐는지는 Status 열에 나옵니다.

Settings, AI, MCP Servers를 열고 Add Server에서 Add Local Server를 고르거나, Zed의 settings.json에 다음을 추가하세요.

{
  "context_servers": {
    "droidline": { "command": "droidline", "args": ["mcp"], "env": {} }
  }
}

MCP Servers에서 droidline 옆의 점이 초록색이면 서버가 동작 중입니다.

표준 입출력으로 서버를 시작할 수 있는 MCP 클라이언트라면 무엇이든 됩니다. 다음 명령을 실행하도록 설정하세요.

droidline mcp

필요한 환경 변수는 없습니다. DROIDLINE_DEVICE, DROIDLINE_TOKEN 같은 설정이 있으면 읽어 들입니다.

폰 고르기

온라인인 폰이 한 대면 에이전트는 그 폰을 씁니다. 여러 대면 에이전트가 devices를 호출하고, 도구마다 device를 넘깁니다. 기본으로 쓸 폰을 정하려면 --device를 추가하세요. 에이전트가 도구를 부를 때 다른 폰 이름을 넘기면 그 폰도 쓸 수 있어서, 제한이 아니라 기본값입니다.

{
  "mcpServers": {
    "droidline": { "command": "droidline", "args": ["mcp", "--device", "shelf-01"] }
  }
}

이름과 폰이 서로 다른 항목을 두 개 만들면, 어시스턴트 하나가 폰 두 대를 이름으로 구분해 쓸 수 있습니다.

좋은 결과를 얻는 요청

에이전트는 목표가 분명하고 그 목표를 확인할 방법이 있을 때 가장 잘합니다. 잘 통하는 프롬프트 몇 가지입니다.

  • "내 폰에서 설정을 열고 어떤 Wi-Fi 네트워크에 연결돼 있는지 알려 줘."
  • "데모 앱에서 knife로 로그인한 다음, 메인 화면의 잔액을 읽어 줘."
  • "스크린샷을 찍고, 이 팝업을 닫는 버튼을 찾아서 눌러 줘."
  • "방금 한 작업을 droidline 패키지를 써서 Python 스크립트로 작성해 줘."

마지막 요청은 좋은 습관입니다. 새 앱은 에이전트가 한 번 살펴보게 한 다음, 그 과정을 에이전트 없이 실행할 수 있는 스크립트로 바꾸세요.

에이전트가 쓸 수 있는 도구 줄이기

기본으로는 Droidline의 모든 명령이 도구로 나옵니다. 단, sms, calls, contacts는 --tools에 이름을 넣었을 때만 나옵니다. 0.1.6부터 있는 두 옵션으로 범위를 줄일 수 있습니다.

  • --tools는 에이전트가 보고 호출할 수 있는 도구만 나열합니다. 목록에 없는 도구를 호출하면 거절하고, 이름을 잘못 쓰면 droidline mcp가 시작하지 않습니다.
  • --read-only는 dump, screenshot, ocr, exists, notifications처럼 폰을 보기만 하는 도구만 남깁니다. 누르기, 입력, 앱 열기, 설정 바꾸기는 하나도 남지 않습니다.
{
  "mcpServers": {
    "droidline-look": { "command": "droidline", "args": ["mcp", "--read-only"] },
    "droidline-tap": { "command": "droidline", "args": ["mcp", "--tools", "dump,screenshot,touch"] }
  }
}

두 옵션을 함께 쓰면 둘 다 통과한 도구만 남습니다. batch 안의 단계도 똑같이 확인하므로, 에이전트에게 주지 않은 도구를 batch로 돌려 실행할 수는 없습니다. 이 옵션은 클라이언트가 droidline mcp를 실행하는 설정에 들어 있어서 에이전트가 바꿀 수 없습니다. 폰을 페어링하거나 이름을 바꾸거나 권한을 취소하는 명령은 처음부터 도구가 아닙니다.

연결할 대상에 주의하기

droidline mcp에 연결된 에이전트는 메시지 보내기, 설정 바꾸기를 포함해 사람이 폰에서 할 수 있는 일을 무엇이든 할 수 있습니다. Droidline은 평범한 버튼과 전송이나 결제 버튼을 구분하지 못해서, touch를 쓸 수 있는 에이전트는 둘 다 누를 수 있습니다. 시험해 보는 동안에는 테스트용 폰이나 개인 계정이 없는 폰을 쓰고, 작업에 필요한 도구만 주세요. 그리고 clear_data, input, notification_reply처럼 데이터를 바꾸는 명령에 대해서는 클라이언트의 도구별 확인 기능을 켜 두세요.