从零构建 Android 开发 MCP 服务：TaoToken 统一 Key 接入与 adb 工具链配置实践

1. 为什么 Android 开发需要一个本地 MCP 服务如果你正在做 Android 开发大概率已经习惯了这样的循环改一版代码装到真机上手动点几下看 Logcat 有没有报错再截个图对比 UI。这套动作本身不复杂但重复几十次之后时间就被切得很碎。AI Agent 能帮忙写代码、改 bug可它看不到你的屏幕、读不到你的日志每次都得你手动把信息喂给它效率提升有限。MCPModel-Controlled Procedures服务解决的就是这个断层。它本质上是跑在你本机的一个进程把 adb 的能力封装成一组标准化的工具让 AI Agent 可以自主调用。Agent 想知道当前界面长什么样就调get_ui_dump想确认按钮点没点中就调get_screenshot想复现一个崩溃就调get_logcat_output。整个过程不需要你反复复制粘贴。这篇文章面向的是有 Android 开发基础、想自己搭一套 MCP 服务把 adb 工具链接进来的工程师。我会从零开始用 Python 写一个最小可运行的 MCP 服务端把 adb 的常用操作注册成工具再通过 TaoToken 统一 Key 接入模型能力最后用 MCP Inspector 验证整条链路。全程可复制配置和命令都给出踩过的坑也会标出来。适合谁手上有真机或模拟器、装了 adb、想用 AI Agent 辅助调试的 Android 开发者。不需要你精通 Python但至少要能看懂函数和命令行参数。2. TaoToken 前置统一 Key 与接入准备在写 MCP 服务之前先把模型接入这块理清楚。MCP 服务本身只负责暴露工具真正做决策的是背后的 AI Agent。Agent 要调用模型就需要一个稳定的 API 入口。TaoToken 在这里的角色是统一 Key 管理你不需要为每个模型单独申请一套凭证一个 Key 就能覆盖对话、编码、Agent 等场景。先到官网注册并拿到 API Keyhttps://taotoken.net/?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content拿到 Key 之后进入控制台创建或查看已有的 Keyhttps://taotoken.net/console?utm_sourcetaotoken_aicg_blog_endutm_contentconsoleAPI 的基础地址是https://taotoken.net/api这个地址在后续配置 MCP 服务的模型调用时会用到。注意API 地址不带 UTM 参数直接写就行。如果你打算长期用 AI Agent 做编码和调试建议看一下 Coding Plan它更适合高频调用的场景https://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_contentcoding-planKey 的管理页面在这里可以随时查看用量和重置https://taotoken.net/api-keys?utm_sourcetaotoken_aicg_blog_endutm_contentapi-keys接入文档在https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_contentdoc模型对话的调试入口https://taotoken.net/?utm_sourcetaotoken_aicg_blog_endutm_contentmodel-chatClaude Code 相关的接入说明https://taotoken.net/claude-code-anthropic?utm_sourcetaotoken_aicg_blog_endutm_contentclaude-code这些链接里官网和 API 地址是必须的其余按需取用。Key 拿到后先放一边后面配置 MCP 服务时会用到。3. 可复制配置MCP 服务骨架与 adb 工具注册3.1 项目初始化与依赖我用uv来管理 Python 环境它比 pip 快很多虚拟环境创建也干净。如果你习惯 venv pip把命令替换掉即可。uv init android-mcp-server cd android-mcp-server编辑pyproject.toml声明依赖[project] name android-dev-mcp-server version 1.0.0 description An MCP Server for Android Development readme README.md requires-python 3.10 dependencies [ mcp[cli]1.22.0, Pillow10.3.0, ]同步依赖uv sync确保 adb 已经安装并加入 PATH执行adb devices能看到设备列表。如果这一步报错先解决 adb 环境问题MCP 服务本身不负责安装 adb。3.2 启动参数设计在项目根目录创建main.py先写参数解析部分。三个关键参数--mode选择传输模式--temp-dir指定临时文件目录--port用于 HTTP 模式。import argparse def parse_args() - tuple[str, str, int]: parser argparse.ArgumentParser(descriptionAndroid Development MCP Server) parser.add_argument( --mode, destmode, typestr, choices[stdio, streamable-http, sse], requiredTrue, helpThe mode to run the MCP server in., ) parser.add_argument( --temp-dir, desttemp_dir, typestr, requiredTrue, helpAbsolute path to a temporary directory for the MCP server., ) parser.add_argument( --port, destport, typeint, default3001, helpThe port to run the MCP server on for HTTP-based modes., ) args parser.parse_args() return args.mode, args.temp_dir, args.portstdio模式适合本地调试Agent 和 MCP 服务在同一台机器上通过标准输入输出通信。streamable-http和sse适合跨机器部署但生产环境一定要加鉴权。3.3 adb 辅助函数与工具注册继续在main.py里添加导入和辅助函数import io import os import subprocess import shlex import xml.etree.ElementTree as ET from mcp.server.fastmcp import FastMCP, Image from mcp.server.fastmcp.exceptions import ToolError from PIL import Image as PILImage from pydantic import Field def call_adb_silent(args: list[str]): 静默执行 adb 命令不关心输出。 subprocess.run( [adb] args, checkTrue, stdoutsubprocess.DEVNULL, stderrsubprocess.DEVNULL, )然后是start_server函数所有工具都定义在里面def start_server(mode: str, temp_dir: str, port: int): os.makedirs(temp_dir, exist_okTrue) mcp FastMCP( nameAndroid Development MCP Server, portport, )接下来逐个注册工具。先看日志获取mcp.tool(structured_outputTrue) def get_logcat_output( app_package: str Field(descriptionThe base package of the app to get the logs from.), log_level: str Field( descriptionThe log level to filter (DEBUG, WARNING, ERROR)., defaultDEBUG, ), ) - str: Retrieves the last 100 lines of logs from the connected Android device. log_level_map {DEBUG: D, WARNING: W, ERROR: E} if log_level.upper() not in log_level_map: raise ToolError(fInvalid log level: {log_level}.) try: result subprocess.run( [adb, logcat, -d, -t, 100, f*:{log_level_map[log_level.upper()]}], capture_outputTrue, textTrue, checkTrue, ) filtered_lines [ line for line in result.stdout.splitlines() if app_package in line ] return \n.join(filtered_lines) except subprocess.CalledProcessError as e: raise ToolError(fError getting logcat output: {e.stderr})截图工具用 Pillow 缩放减少传输量mcp.tool() def get_screenshot() - Image: Gets a screenshot of the connected Android device. try: screenshot_path os.path.join(temp_dir, screenshot.png) call_adb_silent([shell, screencap, -p, /sdcard/screenshot.png]) call_adb_silent([pull, /sdcard/screenshot.png, screenshot_path]) call_adb_silent([shell, rm, /sdcard/screenshot.png]) with PILImage.open(screenshot_path) as img: scale_factor 0.5 new_width int(img.width * scale_factor) new_height int(img.height * scale_factor) resized_img img.resize((new_width, new_height)) buffered io.BytesIO() resized_img.save(buffered, formatPNG) img_bytes buffered.getvalue() os.remove(screenshot_path) return Image(dataimg_bytes, formatpng) except Exception as e: raise ToolError(fError getting screenshot: {e})UI 层级 dump允许 Agent 指定只返回关心的属性mcp.tool(structured_outputTrue) def get_ui_dump( returned_attributes: str Field( descriptionComma-separated attributes to return, e.g., bounds,class,text,clickable. ) ) - str: Gets the UI hierarchy dump as an XML string. if not returned_attributes: raise ToolError(The returned_attributes argument cannot be empty.) attributes_to_keep {attr.strip() for attr in returned_attributes.split(,)} try: dump_path os.path.join(temp_dir, window_dump.xml) call_adb_silent([shell, uiautomator, dump]) call_adb_silent([pull, /sdcard/window_dump.xml, dump_path]) call_adb_silent([shell, rm, /sdcard/window_dump.xml]) with open(dump_path, r, encodingutf-8) as f: ui_dump f.read() os.remove(dump_path) root ET.fromstring(ui_dump) for node in root.iter(): unwanted_attrs [ attr for attr in node.attrib if attr not in attributes_to_keep ] for attr in unwanted_attrs: del node.attrib[attr] return ET.tostring(root, encodingunicode) except Exception as e: raise ToolError(fError getting UI dump: {e})操作类工具点击、滑动、输入、系统按键mcp.tool(structured_outputTrue) def tap_screen( x: int Field(descriptionx-coordinate), y: int Field(descriptiony-coordinate), ) - str: Taps on the screen at the given coordinates. try: call_adb_silent([shell, input, tap, str(x), str(y)]) return fTapped at ({x}, {y}). except Exception as e: raise ToolError(fError tapping on screen: {e}) mcp.tool(structured_outputTrue) def swipe_screen(x1: int, y1: int, x2: int, y2: int) - str: Swipes on the screen from a starting point to an ending point. try: call_adb_silent([shell, input, swipe, str(x1), str(y1), str(x2), str(y2)]) return fSwiped from ({x1}, {y1}) to ({x2}, {y2}). except Exception as e: raise ToolError(fError swiping on screen: {e}) mcp.tool(structured_outputTrue) def send_text( text_to_send: str Field(descriptionThe text to send.) ) - str: Sends the given text, as if typed on a keyboard. if not text_to_send: raise ToolError(Text cannot be empty.) try: escaped_text shlex.quote(text_to_send) call_adb_silent([shell, input, text, escaped_text]) return fSent text: {text_to_send} except Exception as e: raise ToolError(fError sending text: {e}) mcp.tool(structured_outputTrue) def perform_system_action( action: str Field(descriptionSystem action: BACK, HOME, or RECENT_APPS.) ) - str: Performs a system action like back, home, or recent apps. action_map { BACK: KEYCODE_BACK, HOME: KEYCODE_HOME, RECENT_APPS: KEYCODE_APP_SWITCH, } if action.upper() not in action_map: raise ToolError( fInvalid action: {action}. Possible actions: BACK, HOME, RECENT_APPS. ) try: call_adb_silent([shell, input, keyevent, action_map[action.upper()]]) return fPerformed action: {action}. except Exception as e: raise ToolError(fError performing system action: {e})最后是启动逻辑和入口print(fStarting Android MCP Server in {mode} mode...) if mode stdio: mcp.run(transportstdio) elif mode streamable-http: print(fRunning on http://localhost:{port}/mcp) mcp.run(transportstreamable-http) elif mode sse: print(fRunning on http://localhost:{port}/sse) mcp.run(transportsse) else: print(fUnsupported mode: {mode}) if __name__ __main__: mode_arg, temp_dir_arg, port_arg parse_args() start_server(modemode_arg, temp_dirtemp_dir_arg, portport_arg)到这里一个包含 7 个工具的 MCP 服务就写完了。每个工具的 docstring 会成为 Agent 看到的描述Field里的 description 是参数说明这两处写清楚Agent 才知道什么时候该调哪个工具。4. 验证请求MCP Inspector 联通与 adb 调用实测代码写完必须验证。MCP Inspector 是官方提供的调试工具可以在没有 Agent 的情况下直接测试工具。在项目根目录创建mcp-inspector-config.json{ mcpServers: { android-stdio: { command: uv, args: [ run, main.py, --mode, stdio, --temp-dir, /tmp/android_mcp ] }, android-http: { type: streamable-http, url: http://127.0.0.1:3001/mcp } } }Windows 用户把--temp-dir改成C:/Temp/android_mcp这类有效路径。确保uv在 PATH 中。启动 Inspectornpx modelcontextprotocol/inspectorlatest --config mcp-inspector-config.json --server android-stdio浏览器会自动打开一个界面左侧列出所有注册的工具。先测get_ui_dump参数填bounds,text,clickable,resource-id点 Run。如果设备连接正常下方会返回处理过的 XML 数据只保留了你指定的属性。再测get_screenshot返回的是一张 PNG 图片尺寸是原屏幕的一半。如果图片能正常显示说明 adb 截图、拉取、缩放、清理这条链路是通的。测tap_screen填一个坐标比如540,1200观察设备屏幕是否有反应。如果没反应先确认adb devices能看到设备再确认坐标在屏幕范围内。get_logcat_output测的时候app_package填你的应用包名log_level填ERROR看是否能过滤出错误日志。如果返回空可能是最近 100 行里没有该包名的日志换个级别或先手动触发一条日志再试。所有工具都验证通过后把 MCP 服务接入你的 AI Agent。以 stdio 模式为例Agent 侧的配置大致如下{ mcpServers: { android-dev: { command: uv, args: [ run, main.py, --mode, stdio, --temp-dir, /tmp/android_mcp ] } } }Agent 启动时会自动发现这 7 个工具并根据任务需要调用。模型侧的 API 地址填https://taotoken.net/apiKey 用你在 TaoToken 控制台创建的那个。5. 本篇常见错排查5.1 adb devices 看不到设备这是最常见的问题。先检查 USB 线是否支持数据传输有些线只能充电。然后在手机上确认开发者选项和 USB 调试已开启并且弹出了“信任这台电脑”的授权框。如果之前拒绝过到开发者选项里撤销 USB 调试授权重新插拔。网络 adb 的情况确保手机和电脑在同一网段且没有开启 AP 隔离。adb connect的地址格式是IP:端口端口默认 5555但不同设备可能不同。5.2 uiautomator dump 返回空或报错部分设备或系统版本对uiautomator dump的支持有差异。如果返回的 XML 为空先手动执行adb shell uiautomator dump看设备端是否正常生成文件。如果设备端正常但拉取失败检查/sdcard/window_dump.xml的权限。另外uiautomator dump在某些界面如视频播放、游戏可能拿不到完整层级这是系统限制不是 MCP 服务的问题。5.3 input text 无法输入中文或特殊字符adb shell input text对中文和部分特殊字符支持有限。shlex.quote能处理空格和 shell 特殊符号但中文需要额外方案。简单场景可以用 ADBKeyboard 这类输入法替代复杂场景建议在 MCP 工具里集成第三方库。5.4 截图或 UI Dump 太慢screencap和uiautomator dump本身有耗时尤其在低端设备上。优化方向截图缩放比例调小比如从 0.5 降到 0.3get_ui_dump只请求必要的属性减少 XML 体积如果 Agent 不需要每次都看全量 UI可以在 prompt 里引导它优先用get_ui_dump定位元素只在必要时才调get_screenshot。5.5 MCP Inspector 连不上 stdio 服务检查mcp-inspector-config.json里的command是否在 PATH 中。如果用的是uv确认uv已安装且版本支持uv run。--temp-dir指向的目录必须存在且可写Windows 下路径分隔符用正斜杠或双反斜杠。如果 Inspector 启动后界面空白看终端有没有报错。常见的是 Python 依赖没同步执行uv sync后重试。5.6 工具调用返回 ToolError 但信息不明确ToolError会把错误信息返回给 Agent所以错误描述要写清楚。比如 adb 命令失败时把e.stderr带上Agent 才能知道是设备未连接还是权限不足。不要用裸的except Exception吞掉错误至少把异常类型和消息拼进去。6. 接入文档与后续扩展MCP 服务跑通之后下一步可以按需扩展。如果你主要用 Agent 做日常编码和调试Coding Plan 的调用额度更适合高频场景https://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_contentcoding-plan需要查看或重置 Key到 API Keys 页面https://taotoken.net/api-keys?utm_sourcetaotoken_aicg_blog_endutm_contentapi-keys接入过程中遇到协议或参数问题查接入文档https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_contentdoc想先手动验证模型对话是否正常用模型对话入口https://taotoken.net/?utm_sourcetaotoken_aicg_blog_endutm_contentmodel-chatClaude Code 相关的配置参考https://taotoken.net/claude-code-anthropic?utm_sourcetaotoken_aicg_blog_endutm_contentclaude-code扩展方向有几个把常用的 adb 脚本封装成组合工具比如“打开应用并登录”给 HTTP 模式加 Token 鉴权中间件把 MCP 服务接入 CI 流水线在 E2E 测试失败时自动让 Agent 分析截图和日志。这些都可以在当前骨架上叠加不需要重写。最后提醒一句adb 通道本身权限很大MCP 服务只应在可信的开发环境运行。不要在没有鉴权和网络隔离的情况下把 HTTP 模式暴露到公网。