Android Source Explorer MCP Server
MCP server for exploring AOSP internals and Jetpack libraries.
Purpose
When building Android applications, AI tools often rely on outdated training data or incomplete summaries of the Android Framework. This MCP server provides on-demand, precise access to the actual source code (AOSP and AndroidX), enabling the AI to understand complex framework internals like the Activity lifecycle, ViewModel restoration, or Compose internals directly from the truth.
Installation & Setup
Prerequisites
- uv (Recommended) or Python 3.11+
- Git
Recommended Installation (via uv)
The easiest way to install and keep android-source-explorer up to date is using uv. It handles dependencies (including native ones like Tree-sitter and Cryptography) reliably across platforms.
uv tool install git+https://github.com/mrmike/android-source-explorer-mcp
This will make the android-source-explorer command available globally in your PATH.
Initial Sync
After installation, you need to perform an initial sync to fetch the Android source code:
# Sync API 36 (Android 16) and common AndroidX packages
android-source-explorer sync --api-level 36 --androidx "compose,lifecycle,activity"
# (Optional) Download LSP servers for cross-file features
android-source-explorer sync --lsp
Check sync status:
android-source-explorer status
Keeping Sources Up-to-Date
To check for and download the latest available Android Framework revisions (AOSP tags) and newer stable versions of your synced AndroidX packages, run:
# Update all synced framework APIs and AndroidX packages, then rebuild the index
android-source-explorer update
# (Optional) Clean up older versions of updated AndroidX packages
android-source-explorer update --clean
# Update only a specific API level or AndroidX package
android-source-explorer update --api-level 36
android-source-explorer update --androidx activity-compose
Configuration
Add the MCP server to your configuration file (e.g., Claude Desktop, Cursor, Gemini CLI).
Global Usage (Recommended)
If installed via uv tool install, the tool is available globally.
Basic Setup:
{
"mcpServers": {
"android-sources": {
"command": "android-source-explorer",
"args": ["serve"]
}
}
}
With LSP Features Enabled:
{
"mcpServers": {
"android-sources": {
"command": "android-source-explorer",
"args": ["serve"],
"env": {
"ANDROID_SOURCE_LSP": "true"
}
}
}
}
Development Usage
If you cloned the repository and want to run it from the source:
{
"mcpServers": {
"android-sources": {
"command": "uv",
"args": ["run", "--directory", "/absolute/path/to/android-source-explorer", "android-source-explorer", "serve"]
}
}
}
How It Works
1. Hybrid Architecture (Tree-sitter + LSP)
The server uses a dual-engine approach to balance speed and intelligence:
- Tree-sitter (Surgical Engine): Provides near-instant (sub-10ms) AST parsing of single files. It precisely extracts method bodies (including Javadoc and annotations), class members, and inheritance hierarchies without the overhead of a full compiler.
- LSP (Global Engine): Optionally leverages the Eclipse JDT LS (Java) and Kotlin Language Server for cross-file navigation. This enables finding references across millions of lines of code and resolving types that span multiple libraries.
2. Local Sync Strategy
To ensure all lookups are instant and offline-ready, the server uses a sync or update command to manage sources in a local cache (~/.android-sources/):
- AOSP: Fetches framework sources directly from
android.googlesource.com using git sparse-checkouts.
- AndroidX: Downloads
-sources.jar files from the Google Maven repository (dl.google.com/dl/android/maven2/).
- Hybrid Indexing: Prioritizes your local
$ANDROID_HOME sources if available, supplemented by the downloaded cache.
- Automatic Updates: The
update command queries remote endpoints (AOSP Git tags & Google Maven indexes) for updates, downloads newer revisions/versions, and rebuilds the class index.
*Requires ANDROID_SOURCE_LSP=true
License
Apache License 2.0
