Skip to main content
Glama
jeanchristophe13v

gemini-cli-mcp-async

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-async

Configure 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:

  1. Generate unit tests for utils.py

  2. Refactor database.py to use async/await

  3. 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 mode

  • yolo - Auto-confirm prompts

  • approval_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.py

  • Restart 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 capture

  • Check disk space in /tmp

Requirements

  • Python 3.8+

  • uvx

  • Gemini CLI installed

License

MIT License


Questions? Open an issue on GitHub.

Available Tools

3 tools
gemini_cli_check_resultB

Check the status of an async Gemini CLI task. Returns running/completed status and the result if available.

ParametersJSON Schema
NameRequiredDescriptionDefault
task_idYesThe task_id returned by gemini_cli_execute_async

TDQS

B3.3/5.0
Behavior2/5

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.

Conciseness5/5

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.

Completeness3/5

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.

Parameters3/5

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.

Purpose4/5

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.

Usage Guidelines3/5

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.

ParametersJSON Schema
NameRequiredDescriptionDefault
yoloNoEnable auto confirmation (--yolo)
debugNoEnable debug logging (--debug)
queryNoQuery or command arguments passed to Gemini CLI (positional arguments).
sandboxNoEnable sandbox mode (--sandbox)
timeoutNoTimeout in seconds for synchronous execution
extensionsNoGemini CLI extensions (--extensions)
working_dirNoWorking directory for the command (default: current directory)
allowed_toolsNoWhitelisted tool names (--allowed-tools)
approval_modeNoApproval mode (--approval-mode)
output_formatNoOutput format (--output-format)
screen_readerNoEnable screen reader mode (--screen-reader)
additional_argsNoAdditional CLI arguments appended verbatim
experimental_acpNoEnable experimental ACP (--experimental-acp)
include_directoriesNoAdditional directories (--include-directories)
allowed_mcp_server_namesNoWhitelisted MCP server names (--allowed-mcp-server-names)

TDQS

B3.3/5.0
Behavior2/5

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.

Conciseness4/5

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.

Completeness2/5

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.

Parameters3/5

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.

Purpose5/5

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.

Usage Guidelines3/5

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.

ParametersJSON Schema
NameRequiredDescriptionDefault
yoloNoEnable auto confirmation (--yolo)
debugNoEnable debug logging (--debug)
queryNoQuery or command arguments passed to Gemini CLI (positional arguments).
sandboxNoEnable sandbox mode (--sandbox)
extensionsNoGemini CLI extensions (--extensions)
working_dirNoWorking directory for the command (default: current directory)
allowed_toolsNoWhitelisted tool names (--allowed-tools)
approval_modeNoApproval mode (--approval-mode)
output_formatNoOutput format (--output-format)
screen_readerNoEnable screen reader mode (--screen-reader)
additional_argsNoAdditional CLI arguments appended verbatim
experimental_acpNoEnable experimental ACP (--experimental-acp)
include_directoriesNoAdditional directories (--include-directories)
allowed_mcp_server_namesNoWhitelisted MCP server names (--allowed-mcp-server-names)

TDQS

A4.1/5.0
Behavior4/5

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.

Conciseness5/5

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.

Completeness3/5

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.

Parameters3/5

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.

Purpose5/5

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.

Usage Guidelines4/5

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.

  1. 3 tool updatesv0.1.1
    • First observedgemini_cli_check_result
    • First observedgemini_cli_execute
    • First observedgemini_cli_execute_async

TDQS

A3.9/5.0

Scored across 3 tools

Disambiguation5/5

The three tools are clearly distinct: synchronous execution, asynchronous task start, and result checking. The descriptions reinforce the differences, leaving no meaningful overlap.

Naming Consistency5/5

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.

Tool Count5/5

Three tools is an appropriate minimal set for a focused async execution wrapper. Each tool serves a necessary and non-redundant role.

Completeness4/5

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

ActivityInactive
ResponsivenessNo issues

Related MCP Connectors

Related MCP Servers