convez.ai
MCP Server
cyclops-top

android-mcp

cyclops-top/android-mcp

Ver no GitHub
InicialPluginScore · de 0 a 100

MCP (Model Context Protocol) Server Library for Android. Embed an MCP server directly inside your Android app, allowing AI agents to interact with your app's data and features at runtime — query databases, invoke business logic, read device state, and more, all through the standard MCP protocol.

Instalação

$npx convez-ai cyclops-top/android-mcp

1 comando no terminal: detecta o formato do repositório (marketplace ou plugin avulso) e instala via Claude Code. Requer Node 18+ e o Claude Code instalado.

Métricas

Estrelas
1
Forks
0
Acompanhando
0
Saúde
28%
Último commit
há 5 meses
Versão
1.0.3
Issues abertas
0
Contribuidores
3

README

A tradução para o português deste README ainda está na fila.

AndroidMcp

MCP (Model Context Protocol) server library for Android. Embed an MCP server directly inside your Android app — AI agents can query databases, invoke business logic, and interact with your app at runtime through the standard MCP protocol.

Architecture

┌──────────────────────────────────────────┐
│  AI Client (Claude Desktop / Cursor)     │
└──────────────┬───────────────────────────┘
               │ Streamable HTTP (via adb forward)
┌──────────────▼───────────────────────────┐
│  Android Device                          │
│  ┌────────────────────────────────────┐  │
│  │  Ktor CIO embedded server          │  │
│  │  ┌──────────────────────────────┐  │  │
│  │  │  McpServer                    │  │  │
│  │  │  ┌────────────────────────┐  │  │  │
│  │  │  │  McpToolRegistry        │  │  │  │
│  │  │  │  (auto-discovers tools) │  │  │  │
│  │  │  └────────────────────────┘  │  │  │
│  │  └──────────────────────────────┘  │  │
│  └────────────────────────────────────┘  │
│  ┌────────────────────────────────────┐  │
│  │  Plugins (android-mcp-room-tools)  │  │
│  │  → @McpTool methods auto-registered│  │
│  └────────────────────────────────────┘  │
└──────────────────────────────────────────┘

Quick Start

1. Define a tool

@Singleton
class GreetingTool @Inject constructor() : McpToolMarker {

    @McpTool(name = "hello", description = "Say hello to the user")
    suspend fun hello(
        @McpParam(name = "name", description = "Your name") name: String
    ): ToolResult {
        return ToolResult.Text("Hello, $name!")
    }
}

2. Register tool and configure server

@Module
@InstallIn(SingletonComponent::class)
object AppModule {

    @Provides
    @Singleton
    fun provideMcpConfig(): McpConfig = McpConfig(
        name = "my-app-mcp",
        port = 11432,
        debug = true,
    )

    @Provides
    @IntoSet
    fun provideGreetingTool(tool: GreetingTool): McpToolMarker = tool
}

3. Connect

The server auto-starts via AppStartup. Forward the port and connect:

adb forward tcp:11432 tcp:11432

Then add to your MCP client config:

{
  "mcpServers": {
    "my-app": {
      "url": "http://localhost:11432/"
    }
  }
}

Modules

ModulePurposeShips in release
commonShared types: McpConfig, McpToolMarker, annotations, ToolResultYes
mcpKtor server, McpToolRegistry, auto-start via AppStartupYes
android-mcp-room-coreAbstract interfaces: McpDatabaseProvider, McpRoom2DatabaseProvider, McpRoom3DatabaseProviderYes
android-mcp-room2Room 2.x adapter defaults for McpRoom2DatabaseProviderYes
android-mcp-room3Room 3.x adapter defaults for McpRoom3DatabaseProviderYes
android-mcp-room-toolsDebug MCP tools: list_databases, inspect_schema, execute_sqlDebug only
sampleDemo app with Room database + tools—

The split between android-mcp-room-core (always included, no MCP dependency) and android-mcp-room-tools (debug-only, depends on :mcp) means Room database tooling should be added with debugImplementation and kept out of release builds.

Room Tools

The built-in android-mcp-room-tools module exposes your Room databases as MCP tools:

list_databases  → "sample.db - 示例用户数据库"
inspect_schema  → GET DDL for all tables
execute_sql     → Run raw SQL, returns CSV

android-mcp-room-tools is intended for developer builds. By default, execute_sql allows write statements so developers can inspect and repair local debug data quickly. If your workflow needs a read-only debug surface, provide a RoomMcpConfig with SqlPolicyConfig(allowWrites = false).

Add the core provider API, the adapter that matches your Room generation, and the debug-only tools:

implementation("top.cyclops:android-mcp-room-core:<version>")

// Room 2.x / androidx.room
implementation("top.cyclops:android-mcp-room2:<version>")

// Room 3.x / androidx.room3
implementation("top.cyclops:android-mcp-room3:<version>")

debugImplementation("top.cyclops:android-mcp-room-tools:<version>")

Then implement a provider and register it:

// 1. Implement a Room 2.x provider
class SampleRoom2Provider @Inject constructor(
    override val database: AppDatabase,
) : Room2DatabaseProvider {
    override val name: String = "sample.db"
    override val description: String = "User database with users table (id, name, email)"
}

// 2. Bind it into the set — tools are auto-discovered
@Module
@InstallIn(SingletonComponent::class)
object AppModule {
    @Provides @IntoSet
    fun provideRoomProvider(provider: SampleRoom2Provider): McpDatabaseProvider = provider
}

For Room 3.x, use Room3DatabaseProvider instead:

class SampleRoom3Provider @Inject constructor(
    override val database: AppDatabase,
) : Room3DatabaseProvider {
    override val name: String = "sample.db"
    override val description: String = "User database with users table (id, name, email)"
}

Creating Custom Plugins

Any class implementing McpToolMarker with @McpTool-annotated methods is auto-discovered. Register it via Hilt @IntoSet:

@Module
@InstallIn(SingletonComponent::class)
abstract class MyPluginModule {
    @Binds @IntoSet
    abstract fun bindMyTool(tool: MyCustomTool): McpToolMarker
}

Configuration

data class McpConfig(
    val name: String = "android-mcp",  // Server name shown to clients
    val port: Int = 8080,             // HTTP port
    val host: String = "0.0.0.0",    // Bind address
    val debug: Boolean = false,       // Enable request/response logging
)

Requirements

  • minSdk 29
  • Kotlin 2.3+
  • Hilt 2.59+

License

Apache 2.0

Ver o original no GitHub

Bom para

Relacionados