Skip to main content
Glama
gemini-cli-mcp-async

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.

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

    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
    ResponsivenessOutdated data

    Related MCP Connectors

    Related MCP Servers