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-async Analyze 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.
Inputs: task_id (required).
gemini_cli_executeB
Execute Gemini CLI synchronously with configurable parameters. Supports both interactive and non-interactive prompts.
Inputs: yolo, debug, query, sandbox, +11 more.
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.
Inputs: yolo, debug, query, sandbox, +10 more.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelogβ¦
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
Stand up ops from Cursor/Claude/Codex; fleets keep running after your session ends.
Work on your own computers from Claude or ChatGPT: run commands, edit and search files.
One thread for every AI assistant you use. Share tasks and context across ChatGPT, Claude and Grok.
Create projects, nodes, and tasks in UluP Spaces by conversation with Claude.
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 gradedqualityDmaintenanceEnables 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.61 npmMIT
- AlicenseAqualityDmaintenanceEnables 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.344 PyPI44MIT
- AlicenseAqualityBmaintenanceEnables 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.9200 npm27MIT