par5-mcp

An MCP (Model Context Protocol) server that enables parallel execution of shell commands and AI coding agents across lists of items. Perfect for batch processing files, running linters across multiple targets, or delegating complex tasks to multiple AI agents simultaneously.

Features

• List Management: Create, update, delete, and inspect lists of items (file paths, URLs, identifiers, etc.)
• Parallel Shell Execution: Run shell commands across all items in a list with batched parallelism
• Multi-Agent Orchestration: Spawn Claude, Gemini, or Codex agents in parallel to process items
• Streaming Output: Results stream to files in real-time for monitoring progress
• Batched Processing: Commands and agents run in batches of 10 to avoid overwhelming the system

Installation

npm install par5-mcp

Or install globally:

npm install -g par5-mcp

Usage

As an MCP Server

Add to your MCP client configuration:

{
  "mcpServers": {
    "par5": {
      "command": "npx",
      "args": ["par5-mcp"]
    }
  }
}

Or if installed globally:

{
  "mcpServers": {
    "par5": {
      "command": "par5-mcp"
    }
  }
}

Available Tools

List Management

create_list

Creates a named list of items for parallel processing.

Parameters:

• items (string[]): Array of items to store in the list

Returns: A unique list ID to use with other tools

Example:

create_list(items: ["src/a.ts", "src/b.ts", "src/c.ts"])
// Returns: list_id = "abc-123-..."

get_list

Retrieves the items in an existing list by its ID.

Parameters:

• list_id (string): The list ID returned by create_list

update_list

Updates an existing list by replacing its items with a new array.

Parameters:

• list_id (string): The list ID to update
• items (string[]): The new array of items

delete_list

Deletes an existing list by its ID.

Parameters:

• list_id (string): The list ID to delete

list_all_lists

Lists all existing lists and their item counts.

Parameters: None

---

Parallel Execution

run_shell_across_list

Executes a shell command for each item in a list. Commands run in batches of 10 parallel processes.

Parameters:

• list_id (string): The list ID to iterate over
• command (string): Shell command with $item placeholder

Variable Substitution:

• Use $item in your command - it will be replaced with each list item (properly shell-escaped)

Example:

run_shell_across_list(
  list_id: "abc-123",
  command: "wc -l $item"
)

This runs wc -l 'src/a.ts', wc -l 'src/b.ts', etc. in parallel.

Output:

• stdout and stderr are streamed to separate files per item
• File paths are returned for you to read the results

run_agent_across_list

Spawns an AI coding agent for each item in a list. Agents run in batches of 10 with a 5-minute timeout per agent.

Parameters:

• list_id (string): The list ID to iterate over
• agent (enum): "claude", "gemini", or "codex"
• prompt (string): Prompt with {{item}} placeholder

Available Agents:

Agent	CLI	Auto-Accept Flag
claude	Claude Code CLI	--dangerously-skip-permissions
gemini	Google Gemini CLI	--yolo
codex	OpenAI Codex CLI	--dangerously-bypass-approvals-and-sandbox

Variable Substitution:

• Use {{item}} in your prompt - it will be replaced with each list item

Example:

run_agent_across_list(
  list_id: "abc-123",
  agent: "claude",
  prompt: "Review {{item}} for security vulnerabilities and suggest fixes"
)

Output:

• stdout and stderr are streamed to separate files per item
• File paths are returned for you to read the agent outputs

Workflow Example

Here's a typical workflow for processing multiple files:

1. Create a list of files to process:

   create_list(items: ["src/auth.ts", "src/api.ts", "src/utils.ts"])
   

2. Run a shell command across all files:

   run_shell_across_list(
     list_id: "<returned-id>",
     command: "cat $item | grep -n 'TODO'"
   )
   

3. Or delegate to AI agents:

   run_agent_across_list(
     list_id: "<returned-id>",
     agent: "claude",
     prompt: "Add comprehensive JSDoc comments to all exported functions in {{item}}"
   )
   

4. Read the output files to check results

5. Clean up:

   delete_list(list_id: "<returned-id>")
   

Configuration

The following environment variables can be used to configure par5-mcp:

Variable	Description	Default
PAR5_BATCH_SIZE	Number of parallel processes per batch	10
PAR5_AGENT_ARGS	Additional arguments passed to all agents	(none)
PAR5_CLAUDE_ARGS	Additional arguments passed to Claude CLI	(none)
PAR5_GEMINI_ARGS	Additional arguments passed to Gemini CLI	(none)
PAR5_CODEX_ARGS	Additional arguments passed to Codex CLI	(none)
PAR5_DISABLE_CLAUDE	Set to any value to disable the Claude agent	(none)
PAR5_DISABLE_GEMINI	Set to any value to disable the Gemini agent	(none)
PAR5_DISABLE_CODEX	Set to any value to disable the Codex agent	(none)

Example:

{
  "mcpServers": {
    "par5": {
      "command": "npx",
      "args": ["par5-mcp"],
      "env": {
        "PAR5_BATCH_SIZE": "20",
        "PAR5_CLAUDE_ARGS": "--model claude-sonnet-4-20250514"
      }
    }
  }
}

Output Files

Results are written to temporary files in the system temp directory under par5-mcp-results/:

/tmp/par5-mcp-results/<run-id>/
  ├── auth.ts.stdout.txt
  ├── auth.ts.stderr.txt
  ├── api.ts.stdout.txt
  ├── api.ts.stderr.txt
  └── ...

File names are derived from the item value (sanitized for filesystem safety).

Development

Building from Source

git clone https://github.com/mathematic-inc/par5-mcp.git
cd par5-mcp
npm install
npm run build

Running Locally

npm start

Requirements

• Node.js 18+
• For run_agent_across_list:
  • claude agent requires Claude Code CLI installed
  • gemini agent requires Gemini CLI installed
  • codex agent requires Codex CLI installed

License

Apache-2.0

This project is free and open-source work by a 501(c)(3) non-profit. If you find it useful, please consider donating.