par5-mcp

An MCP (Model Context Protocol) server that runs shell commands and AI coding agents across lists of items in parallel. Use it to process files in batches, run linters across targets, or delegate work to multiple agents.

Features

• List Management: Create, update, delete, and inspect lists of items such as file paths, URLs, and identifiers

• 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 and 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:

• Standard output and standard error 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:

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:

• Standard output and standard error 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:

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).

Contributing

Please start a Discussion before proposing a change. If we accept the proposal, a Mathematic maintainer or AI agent will implement it and open a pull request. We will link that pull request to the Discussion and credit the proposal's original author. GitHub restricts pull request creation to Mathematic maintainers, repository collaborators with write, maintain, or admin access, and authorized maintenance agents. See CONTRIBUTING.md for the full process.

Development

Building from Source

git clone https://github.com/mathematic-inc/par5-mcp.git
cd par5-mcp
mise install
mise exec -- pnpm install --frozen-lockfile
mise exec -- hk install
mise exec -- pnpm build

Running Locally

mise exec -- pnpm start

Requirements

• Node.js 20+

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