AOSP-MCP

A Bun-powered Model Context Protocol (MCP) server for searching and reading Android source code via cs.android.com. Built for coding agents: compact ripgrep-style results, response caching, request coalescing, and pagination designed around agent token budgets.

Works with Claude Code, Cursor, VS Code Copilot, Zed, Gemini CLI, Codex CLI, Windsurf, and any other MCP client with stdio support.

Preview

Features

• Code search across AOSP, AndroidX/Jetpack, Android Studio, and Android LLVM, with regex and file: / class: / function: / symbol: / content: / lang: operators
• File reading with line numbers, startLine/endLine ranges, and continuation hints for large files
• Symbol suggestions to resolve partial class/method/file names
• Fast: server ready in ~46 ms under Bun (bunx --bun) or ~130 ms under Node (bun run bench reproduces these two numbers on your machine; medians of 9 runs; bunx/npx package-resolution overhead is extra); measured separately at ~ 111 ms for the Node-only predecessor as shipped, making the bun-to-bun rewrite ~20% faster; TLS warm-up on boot; repeat queries served from the in-memory cache in under a millisecond (measured end-to-end over stdio); one fast retry on transient upstream failures
• Token-efficient: concise-by-default search results, deduplicated matches, snippet caps, and short pagination handles; measured search and large-file payloads run 50-85% smaller (~70% typical) than the predecessor's

Installation

The recommended launcher is bunx (Bun 1.3+); npx (Node 20.3+) also works.

Claude Code

claude mcp add aosp -- bunx --bun -y @itznotabug/aosp-mcp

{
  "mcpServers": {
    "aosp": {
      "command": "bunx",
      "args": [
        "--bun",
        "-y",
        "@itznotabug/aosp-mcp"
      ]
    }
  }
}

{
  "servers": {
    "aosp": {
      "type": "stdio",
      "command": "bunx",
      "args": [
        "--bun",
        "-y",
        "@itznotabug/aosp-mcp"
      ]
    }
  }
}

{
  "context_servers": {
    "aosp": {
      "command": "bunx",
      "args": [
        "--bun",
        "-y",
        "@itznotabug/aosp-mcp"
      ]
    }
  }
}

[mcp_servers.aosp]
command = "bunx"
args = ["--bun", "-y", "@itznotabug/aosp-mcp"]

[mcp_servers.aosp.env]
AOSP_MCP_MAX_RESULT_CHARS = "9000"

{
  "mcpServers": {
    "aosp": {
      "command": "bunx",
      "args": [
        "--bun",
        "-y",
        "@itznotabug/aosp-mcp"
      ],
      "trust": true
    }
  }
}

Troubleshooting

• "Executable not found" in GUI-launched editors (macOS): desktop apps often miss your shell PATH. Use the absolute path from which bunx (typically ~/.bun/bin/bunx) as the command.
• No Bun installed: use npx with -y @itznotabug/aosp-mcp in any snippet above.
• Clients that truncate large tool results: lower AOSP_MCP_MAX_RESULT_CHARS (e.g. 9000) to fit your client's limit, as in the Codex example.

Tools

search_android_code

| Parameter | Required | Description | |------------------|----------|----------------------------------------------------------------------------------------------------| | query | Yes | Search query (regex plus file:, class:, function:, symbol:, lang:, content: operators) | | project | No | android, androidx, android-studio, or android-llvm (default: all) | | pageSize | No | Files per page (default 10, max 50) | | pageToken | No | Continuation token from a previous result (e.g. p1) | | contextLines | No | Context lines around matches (default 1, max 10) | | responseFormat | No | concise (default) or detailed |

get_file_content

| Parameter | Required | Description | |--------------|----------|-------------------------------------------------------------------| | project | Yes | Project id | | repository | Yes | Repository, e.g. platform/superproject | | branch | Yes | Branch, e.g. main, android-latest-release | | path | Yes | File path relative to the repository root | | startLine | No | First line to return (1-based) | | endLine | No | Last line to return (inclusive; reads cap at 2000 lines per call) |

suggest_symbols

| Parameter | Required | Description | |--------------|----------|-------------------------------------| | query | Yes | Partial symbol or file name | | maxResults | No | Max suggestions (default 7, max 20) |

list_projects

No parameters. Returns the searchable projects (also as structured content).

Configuration

| Environment variable | Default | Description | |------------------------------|----------|-----------------------------------------------------------------------------------| | AOSP_MCP_TIMEOUT_MS | 30000 | Per-attempt upstream request timeout | | AOSP_MCP_CACHE_TTL_MS | 60000 | Search/suggest cache TTL (0 disables) | | AOSP_MCP_FILE_CACHE_TTL_MS | 300000 | File-content cache TTL (0 disables) | | AOSP_MCP_MAX_RESULT_CHARS | 60000 | Character budget per file-read result (minimum 1000; does not cap search results) |

MCP resources (android://source?...) intentionally return complete files and bypass the character budget. Cached entries are keyed by the full request, so a cache hit is always the answer to the same question; TTLs only bound how long a just-changed branch head can serve a slightly older revision.

Development

bun install        # dependencies
bun run dev        # run the server from TypeScript source
bun test           # test suite (100% coverage thresholds enforced)
bun run lint       # Biome + the strict.grit lint plugin
bun run typecheck  # tsc
bun run build      # bundle to dist/
bun run smoke      # stdio handshake against the built bundle

Tests run against captured live API fixtures (tests/fixtures/) with the network mocked, plus end-to-end MCP client/server tests over an in-memory transport. Refresh fixtures deliberately with bun scripts/fixtures.ts when the upstream response shape changes.

License

Apache 2.0. See NOTICE for attribution.

Based on cs_android_mcp.