gemini-cli-mcp-async
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@gemini-cli-mcp-asyncAnalyze the project code and generate a technical report"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
Gemini CLI MCP Async Server
Asynchronous MCP wrapper for Gemini CLI
Enable Claude Code to spawn child Gemini CLI sessions for parallel task execution.
Features
โ Async execution - Start tasks in background, continue working
โ Multi-instance parallelism - Run multiple Gemini CLI sessions simultaneously
โ Automatic cleanup - No zombie processes
โ Zero config - Works out of the box
Related MCP server: mcp-aider-executor
Quick Start
๐ Install with UVX
Zero configuration - just run:
uvx gemini-cli-mcp-asyncConfigure Claude Code or other MCP Client
Add to your ~/.claude/settings.json:
{
"mcpServers": {
"gemini-cli-mcp": {
"command": "uvx",
"args": ["gemini-cli-mcp-async"],
"env": {}
}
}
}Restart Claude Code
Reload or restart Claude Code to load the MCP server.
Usage Examples
๐ Async Execution (Game Changer!)
Start a long task and continue working immediately:
You:
Please analyze the entire project code and generate a comprehensive technical report
Claude: I'll analyze your entire project and generate a technical report. This is a large task, so I'll start it asynchronously...
โ Task Started (Task ID: abc12345) You can continue working on other things while it runs in the background!
You: (Continue working immediately)
While the report is generating, help me write some unit tests
Claude: Sure! Let me write those unit tests for you...
You: (A few minutes later)
Can you check if the report task is finished?
Claude: โ Report Complete!
[View Detailed Technical Report]
Project structure analysis
Code quality assessment
Performance optimization recommendations
Security audit results
โก Parallel Execution
Run multiple tasks simultaneously:
You:
I need to do three things at once:
Generate unit tests for utils.py
Refactor database.py to use async/await
Add type hints to all functions in api.py
Claude: I'll start all three tasks in parallel!
๐ Task 1 Started (Task ID: task1) - Generating unit tests ๐ Task 2 Started (Task ID: task2) - Refactoring database code ๐ Task 3 Started (Task ID: task3) - Adding type hints
All tasks are running in parallel...
You: (Later)
Are all three tasks finished?
Claude: โ All Complete!
โ Task 1: Unit tests for utils.py generated
โ Task 2: database.py refactored to async mode
โ Task 3: Type hints added to api.py functions
๐ฏ Quick Sync Tasks
For simple immediate tasks:
You:
Write a Python function to validate email addresses
Claude:
import re
def validate_email(email):
pattern = r'^[a-zA-Z0-9._%+-]+@[a-zA-Z0-9.-]+\.[a-zA-Z]{2,}$'
return re.match(pattern, email) is not None
# Usage examples
print(validate_email("user@example.com")) # True
print(validate_email("invalid-email")) # Falseโ Task Complete!
Why Async?
Problem: Gemini CLI blocks the parent session while running.
Solution: This MCP server spawns child Gemini CLI processes that run in the background.
Benefits:
๐ Start a task and continue working immediately
โก Run multiple tasks in parallel
๐ฏ No blocking, no waiting
๐งน Automatic process cleanup
API Reference
gemini_cli_execute(query, working_dir, sandbox, yolo, approval_mode, experimental_acp, allowed_mcp_server_names, allowed_tools, extensions, include_directories, output_format, screen_reader, debug, additional_args, timeout)
Execute Gemini CLI synchronously and return result immediately.
gemini_cli_execute_async(query, working_dir, sandbox, yolo, approval_mode, experimental_acp, allowed_mcp_server_names, allowed_tools, extensions, include_directories, output_format, screen_reader, debug, additional_args)
Start Gemini CLI task in background and return task_id.
gemini_cli_check_result(task_id)
Check status of async task and return result if completed.
Configuration
All Gemini CLI parameters are supported. Key options:
sandbox- Enable sandbox modeyolo- Auto-confirm promptsapproval_mode- Set approval mode ('default', 'auto_edit', 'yolo')output_format- Output format ('text', 'json', 'stream-json')timeout- Timeout for sync execution (seconds)debug- Enable debug logging
Troubleshooting
Server not showing up?
Use absolute path in config
Run:
chmod +x gemini_cli_mcp_async_server.pyRestart Claude Code
Task stuck in "running"?
Wait a moment, large tasks take time
Check:
ls -la /tmp/gemini_cli_tasks/View logs:
tail -f /tmp/gemini_cli_mcp_debug.log
No output from long tasks:
Use
output_format="stream-json"for better output captureCheck disk space in
/tmp
Requirements
Python 3.8+
uvx
Gemini CLI installed
License
MIT License
Questions? Open an issue on GitHub.
Available Tools
3 toolsgemini_cli_check_resultB
Check the status of an async Gemini CLI task. Returns running/completed status and the result if available.
| Name | Required | Description | Default |
|---|---|---|---|
| task_id | Yes | The task_id returned by gemini_cli_execute_async |
TDQS
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations exist, so the description carries the full behavioral disclosure burden. It partially delivers by stating the two statuses and that the result is available conditionally, but it omits failure/error states, whether repeated polling is safe or expected, and any timeout or staleness behavior. For an unannotated tool this is a noticeable gap.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences with zero wasted words. The core action ('Check the status') is front-loaded, and the second sentence efficiently discloses the return behavior.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool is simple (one parameter, no output schema, no annotations), and the description adequately covers main purpose and return values. However, without an output schema it leaves the exact response shape undocumented, and failure states are unaddressed, so the agent may not know how to interpret an unsuccessful task.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the description need not add parameter detail; the task_id parameter is already fully documented in the schema. The description adds no extra meaning about the parameter beyond what the schema provides, warranting the baseline 3.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb ('Check') and resource ('status of an async Gemini CLI task'), and clarifies it returns 'running/completed status and the result if available.' This semantically distinguishes it from the execute siblings, though it does not explicitly name them.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Usage is implied: checking status is the natural follow-up to gemini_cli_execute_async, and the schema's task_id description references that sibling. However, the main description gives no explicit when-to-use guidance, no exclusions, and no mention of when to prefer gemini_cli_execute instead.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
gemini_cli_executeB
Execute Gemini CLI synchronously with configurable parameters. Supports both interactive and non-interactive prompts.
| Name | Required | Description | Default |
|---|---|---|---|
| yolo | No | Enable auto confirmation (--yolo) | |
| debug | No | Enable debug logging (--debug) | |
| query | No | Query or command arguments passed to Gemini CLI (positional arguments). | |
| sandbox | No | Enable sandbox mode (--sandbox) | |
| timeout | No | Timeout in seconds for synchronous execution | |
| extensions | No | Gemini CLI extensions (--extensions) | |
| working_dir | No | Working directory for the command (default: current directory) | |
| allowed_tools | No | Whitelisted tool names (--allowed-tools) | |
| approval_mode | No | Approval mode (--approval-mode) | |
| output_format | No | Output format (--output-format) | |
| screen_reader | No | Enable screen reader mode (--screen-reader) | |
| additional_args | No | Additional CLI arguments appended verbatim | |
| experimental_acp | No | Enable experimental ACP (--experimental-acp) | |
| include_directories | No | Additional directories (--include-directories) | |
| allowed_mcp_server_names | No | Whitelisted MCP server names (--allowed-mcp-server-names) |
TDQS
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description must carry the full burden. It discloses that execution is synchronous and supports interactive/non-interactive prompts, but omits side effects, return values, timeout behavior, and safety implications of running CLI commands. For a command-execution tool, this is a significant gap.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single concise sentence with no meaningful bloat, and the key synchronous behavior is front-loaded. It loses a point for the slightly generic 'with configurable parameters' phrase, which adds little information, but overall it is efficiently written.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given 15 optional parameters, no annotations, and no output schema, a one-sentence description is insufficient. It omits return value semantics, output format behavior, timeout handling, and any warnings about potential system effects, leaving an agent without enough context to invoke the tool confidently.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, with all 15 parameters documented in the input schema. The description only says 'configurable parameters' and adds no parameter-specific meaning beyond what the schema already provides, so the baseline 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific action ('Execute Gemini CLI synchronously') and clearly distinguishes itself from the async sibling by emphasizing synchronous mode. Also notes support for both interactive and non-interactive prompts, giving a clear functional identity.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The word 'synchronously' implies use when blocking execution is desired, and the sibling names hint at an async alternative. However, there is no explicit guidance on when to choose this tool over gemini_cli_execute_async or how gemini_cli_check_result fits in, leaving the selection largely to inference.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
gemini_cli_execute_asyncA
Start a Gemini CLI task in the background and return immediately with a task_id. Use gemini_cli_check_result to retrieve the result.
| Name | Required | Description | Default |
|---|---|---|---|
| yolo | No | Enable auto confirmation (--yolo) | |
| debug | No | Enable debug logging (--debug) | |
| query | No | Query or command arguments passed to Gemini CLI (positional arguments). | |
| sandbox | No | Enable sandbox mode (--sandbox) | |
| extensions | No | Gemini CLI extensions (--extensions) | |
| working_dir | No | Working directory for the command (default: current directory) | |
| allowed_tools | No | Whitelisted tool names (--allowed-tools) | |
| approval_mode | No | Approval mode (--approval-mode) | |
| output_format | No | Output format (--output-format) | |
| screen_reader | No | Enable screen reader mode (--screen-reader) | |
| additional_args | No | Additional CLI arguments appended verbatim | |
| experimental_acp | No | Enable experimental ACP (--experimental-acp) | |
| include_directories | No | Additional directories (--include-directories) | |
| allowed_mcp_server_names | No | Whitelisted MCP server names (--allowed-mcp-server-names) |
TDQS
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of behavioral disclosure. It meaningfully discloses the key non-obvious traits: background execution, immediate return, task_id generation, and deferred result retrieval. It does not cover failure modes or task lifecycle cleanup, but the core caller-affecting behavior is clearly stated.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences with zero filler. The core behavior is front-loaded, and the retrieval instruction is placed immediately after, making the tool's usage flow easy to parse.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool with 14 parameters, no output schema, and no annotations, the description covers the essential flow but leaves gaps around parameter interactions and when async should be preferred over sync execution. It is minimally adequate for selection and invocation but not richly complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 100% parameter description coverage, so the baseline is 3. The description adds no additional parameter-level semantic guidance beyond what the schema already provides.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb and resource: 'Start a Gemini CLI task in the background and return immediately with a task_id.' This clearly distinguishes the tool from its sync sibling by emphasizing background execution and immediate return, and it names the follow-up retrieval path.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly instructs 'Use gemini_cli_check_result to retrieve the result,' giving clear follow-up usage guidance. It does not explicitly contrast this with gemini_cli_execute for choosing sync vs async, so it lacks a full exclusion statement.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
3 tool updates
v0.1.1- First observed
gemini_cli_check_result - First observed
gemini_cli_execute - First observed
gemini_cli_execute_async
TDQS
Scored across 3 tools
The three tools are clearly distinct: synchronous execution, asynchronous task start, and result checking. The descriptions reinforce the differences, leaving no meaningful overlap.
All tools share the gemini_cli_ prefix and follow a consistent snake_case verb_noun pattern: execute, execute_async, check_result. Naming is predictable and uniform.
Three tools is an appropriate minimal set for a focused async execution wrapper. Each tool serves a necessary and non-redundant role.
The core workflow of sync execution, async launch, and result retrieval is covered. Cancellation or task listing is not provided, but the basic async lifecycle is complete enough for most use cases.
Maintenance
Related MCP Connectors
Create projects, nodes, and tasks in UluP Spaces by conversation with Claude.
Deploy, monitor, and manage your OpenClaw AI assistants via natural language.
Persistent context for Claude. Your AI always knows your projects and next actions across sessions.
Source-checked CLI guides and model-aware planning for Claude Code, Codex, and Grok Build.
Related MCP Servers
- FlicenseNot gradedqualityDmaintenanceEnables asynchronous and parallel execution of Claude Code tasks across multiple sessions, allowing users to start background tasks and continue working immediately without blocking.1-
- AlicenseNot gradedqualityCmaintenanceEnables running aider as a detached background process with git and file tools, allowing LLMs to start code editing processes and check progress asynchronously for agentic swarm behavior.39 npmMIT
- AlicenseAqualityCmaintenanceEnables Claude Code to run OpenAI Codex (GPT-5) tasks asynchronously in the background, filtering out thinking logs to save 95% context tokens and allowing parallel execution.344MIT
- AlicenseAqualityAmaintenanceEnables running multiple AI CLI tools (Claude, Codex, Gemini, Forge, OpenCode) as background processes with automatic permission handling, allowing LLMs to execute async multitasking and combine different AI models.9461 npm27MIT