Local Expo MCP

local-expo-mcp is a single user-visible MCP server for local Expo workflows.

It gives agents one local MCP surface for:

• Expo project inspection
• Metro start, stop, restart, status, logs, and recent error summaries
• local Android-capable Expo runs
• hidden expo-mcp attach after Metro is healthy
• device listing and logs
• screenshots, app launch, app terminate, and foreground-app inspection through hidden mobile-mcp
• session summaries for the current project

Scope

Current validated scope is Windows-first local development.

Today:

• Windows is actively implemented and tested
• macOS is deferred
• Linux is not yet validated
• EAS is intentionally out of scope

Why It Exists

Using expo-mcp and mobile-mcp directly means the user has to manage multiple MCP servers and their startup order. local-expo-mcp keeps that orchestration internal:

• one public MCP server only
• direct control of Expo CLI and adb
• lazy hidden child MCP startup only when needed
• structured results instead of raw terminal output

Installation

Requirements:

• Node 20+
• local Expo tooling for the projects you want to work on
• Android tooling on PATH if you want adb fallbacks or local Android runs

Run it locally with npx once published:

npx local-expo-mcp

For repo development:

bun install
bun run build
node dist/server.js

Add It To Your AI Client

local-expo-mcp is a local stdio MCP server. In practice, every client needs the same core launch command:

command: npx
args: [-y, local-expo-mcp]

If a client can run a local stdio MCP server with a command and args array, it can usually run local-expo-mcp.

General MCP Pattern

For clients that support generic stdio MCP configuration, use this shape:

{
  "mcpServers": {
    "local-expo": {
      "command": "npx",
      "args": ["-y", "local-expo-mcp"]
    }
  }
}

If the client is on native Windows and cannot launch npx directly, use a command wrapper that the client supports, for example:

{
  "mcpServers": {
    "local-expo": {
      "command": "cmd",
      "args": ["/c", "npx", "-y", "local-expo-mcp"]
    }
  }
}

Claude

Claude Code supports local stdio MCP servers. Anthropic documents both CLI-based setup and JSON configuration.

Claude Code CLI, native Windows-safe form:

claude mcp add --transport stdio local-expo -- cmd /c npx local-expo-mcp

Note: omit -y on Windows — Claude Code parses it as an unknown option before passing args through.

Claude Code CLI, typical macOS/Linux form:

claude mcp add --transport stdio local-expo -- npx -y local-expo-mcp

Claude project config via .mcp.json:

{
  "mcpServers": {
    "local-expo": {
      "command": "cmd",
      "args": ["/c", "npx", "local-expo-mcp"]
    }
  }
}

Claude Desktop config uses the same mcpServers JSON shape. On Windows that file is typically %APPDATA%\Claude\claude_desktop_config.json.

Codex

Codex supports MCP in its shared CLI and IDE config.

Codex CLI command:

codex mcp add local-expo -- npx -y local-expo-mcp

Project-scoped .codex/config.toml:

[mcp_servers.local-expo]
command = "npx"
args = ["-y", "local-expo-mcp"]
startup_timeout_sec = 30
tool_timeout_sec = 120
enabled = true

Local repo development example:

[mcp_servers.local-expo]
command = "node"
args = ["dist/server.js"]
startup_timeout_sec = 30
tool_timeout_sec = 120
enabled = true

Useful commands:

codex mcp list
codex mcp get local-expo

Gemini

Gemini CLI supports MCP servers through ~/.gemini/settings.json.

Gemini CLI command:

gemini mcp add local-expo npx -y local-expo-mcp

If your Windows Gemini setup cannot launch npx directly, use:

gemini mcp add local-expo cmd /c npx -y local-expo-mcp

Example settings.json:

{
  "mcpServers": {
    "local-expo": {
      "command": "npx",
      "args": ["-y", "local-expo-mcp"],
      "timeout": 30000
    }
  }
}

If your Windows Gemini setup cannot launch npx directly, use:

{
  "mcpServers": {
    "local-expo": {
      "command": "cmd",
      "args": ["/c", "npx", "-y", "local-expo-mcp"],
      "timeout": 30000
    }
  }
}

After configuring it, restart Gemini CLI and inspect MCP status from the CLI.

GitHub Copilot

GitHub Copilot in VS Code supports MCP servers via a .vscode/mcp.json file in your workspace or via VS Code user settings.

Workspace config (.vscode/mcp.json):

{
  "servers": {
    "local-expo": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "local-expo-mcp"]
    }
  }
}

On native Windows, wrap the command:

{
  "servers": {
    "local-expo": {
      "type": "stdio",
      "command": "cmd",
      "args": ["/c", "npx", "local-expo-mcp"]
    }
  }
}

After saving, open the Copilot Chat panel, switch to Agent mode, and the local-expo server will appear in the tools list.

OpenCode

OpenCode supports local MCP servers in opencode.json or opencode.jsonc.

OpenCode CLI command:

opencode mcp add

This will prompt you for the server details. Choose local (stdio) and provide the command npx with arguments -y local-expo-mcp.

Example opencode.json:

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "local-expo": {
      "type": "local",
      "command": ["npx", "-y", "local-expo-mcp"],
      "enabled": true,
      "timeout": 120000
    }
  }
}

OpenCode also exposes MCP helper commands such as opencode mcp list.

Public Tools

Current public tools:

• project_inspect
• metro_start
• metro_stop
• metro_restart
• metro_status
• metro_logs_recent
• metro_errors_recent
• dev_server_attach
• android_run
• device_list
• device_logs_recent
• device_screenshot
• device_app_launch
• device_app_terminate
• device_foreground_app
• session_summary

All tools return structured JSON-like data. Failures use this envelope:

{
  "ok": false,
  "error": {
    "code": "ERROR_CODE",
    "message": "Human readable summary",
    "details": {}
  }
}

Development

Common commands:

bun install
bun run build
bun run commitlint
bunx vitest run
bun run test:windows
bun run test:live:windows
bun run test:acceptance

Live repro apps live under test/live-projects/.

Repo-specific contributor and agent guidance lives in AGENT.md.

Testing

This repo ships with:

• non-live unit and integration coverage
• Windows-specific test coverage
• required Windows live Metro coverage
• repo-owned live Expo smoke projects for regression reproduction

If you are working inside this repo, use the validation guidance in AGENT.md.

CI and Publishing

This repo includes:

• CI for install, commitlint, tests, and build
• a PR-based release workflow in release.yml
• Trusted Publisher (GitHub OIDC) so npm publishing runs without a static NPM_TOKEN
• Dependabot for npm and GitHub Actions updates

Release Process

This repo does not publish directly from a feature PR merge. It uses a two-step flow so main stays PR-only:

1. Merge a normal PR into main with the publish label.
2. The release workflow updates release/next with:
   • the next version in package.json
   • the pending release entry in CHANGELOG.md
   • the pending release state file release-plan.json
3. The workflow creates or updates a PR from release/next into main.
4. Review and merge that release PR.
5. After the release/next PR is merged, the workflow:
   • runs build and tests again
   • publishes to npm with OIDC
   • creates or updates the GitHub release and tag

Version selection is based on the merged PR title/body using conventional-commit style rules:

• feat: -> minor
• fix: and perf: -> patch
• feat!: or BREAKING CHANGE: -> major
• refactor:, build:, and ci: can still produce a patch release
• docs: and test: alone do not create a release PR

If multiple publish-labeled PRs merge before release/next is merged, the pending release PR is updated and the version is escalated as needed.

Troubleshooting

If metro_start fails:

• verify the target project is a local Expo project
• verify the selected port is free
• inspect metro_logs_recent

If android_run fails:

• inspect the structured Gradle summary
• inspect recent device logs
• verify local Android SDK and adb availability

If hidden MCP attachment fails:

• start Metro first
• confirm the dev server URL was detected
• verify local dependencies were installed successfully

Sources For Client Config Examples

These client setup examples were checked against current documentation on March 22, 2026:

• Anthropic Claude Code MCP docs: https://code.claude.com/docs/en/mcp
• OpenAI Docs MCP guide for Codex MCP configuration examples: https://developers.openai.com/learn/docs-mcp
• Gemini CLI repository docs pointing to ~/.gemini/settings.json: https://github.com/google-gemini/gemini-cli
• OpenCode MCP server docs: https://opencode.ai/docs/mcp-servers/

Note

This MCP has been engineered heavily with the aid of AI agents, with human review guiding the architecture, implementation, testing, and release workflow decisions.