# Gptqueue

> Inter-agent message queue over MCP + Redis

- **Type:** MCP server
- **Install:** `agentstack add mcp-rahulrajaram-gptqueue`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [rahulrajaram](https://agentstack.voostack.com/s/rahulrajaram)
- **Installs:** 0
- **Category:** [Databases](https://agentstack.voostack.com/c/databases)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [rahulrajaram](https://github.com/rahulrajaram)
- **Source:** https://github.com/rahulrajaram/gptqueue

## Install

```sh
agentstack add mcp-rahulrajaram-gptqueue
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# gptqueue

[](https://github.com/rahulrajaram/gptqueue/actions/workflows/ci.yml)

Inter-agent message queue over MCP + Redis.

gptqueue lets AI agents (Claude Code, Codex, Gemini CLI, or any MCP-compatible client) discover each other and exchange messages through a shared Redis-backed queue. Each agent registers with a name and description, then sends and receives typed messages via MCP tool calls.

## Architecture

```
┌─────────────┐       MCP (stdio)       ┌──────────────┐
│  AI Agent A  │◄──────────────────────►│              │
└─────────────┘                         │  gptqueue    │       ┌───────┐
                                        │  MCP server  │◄─────►│ Redis │
┌─────────────┐       MCP (stdio)       │              │       └───────┘
│  AI Agent B  │◄──────────────────────►│              │
└─────────────┘                         └──────────────┘
```

Each agent gets its own bounded inbox queue in Redis. Messages are delivered atomically via a Lua script that enforces queue size limits. Agents publish heartbeats so others can see who is online.

## Components

| Component | Description |
|---|---|
| **MCP server** (`src/mcp-server/`) | Stdio-based MCP server exposing 6 tools for agent communication |
| **PTY wrapper** (`src/pty-wrapper/`) | Wraps a CLI process in a PTY, watches Redis for incoming messages, and injects notifications when the process is idle |
| **Hook script** (`scripts/check-queue.sh`) | Claude Code hook for startup context injection and stop-gate (blocks exit if inbox has unread messages) |

## MCP Tools

| Tool | Description |
|---|---|
| `register_agent` | Register with a name, role (`publisher`/`consumer`/`both`), and description |
| `send_message` | Send a typed message (`task`/`result`/`status`/`error`/`ping`) to another agent's inbox. Supports optional `metadata` object and `in_reply_to` message ID for threading |
| `receive_message` | Blocking pop from your inbox (default timeout: 5s) |
| `list_agents` | Discover all registered agents with online/offline status |
| `get_queue_status` | Check queue depth and capacity for one or all agents |
| `unregister_agent` | Unregister and clean up queue data |

## Prerequisites

- **Node.js** >= 18
- **Redis** running locally (default `redis://127.0.0.1:6379`)

## Install

```bash
git clone https://github.com/rahulrajaram/gptqueue.git
cd gptqueue
npm install   # builds automatically via postinstall
```

## Configuration

### Claude Code

Add to `~/.claude.json` under `mcpServers`:

```json
{
  "gptqueue": {
    "type": "stdio",
    "command": "node",
    "args": ["/path/to/gptqueue/dist/mcp-server/index.js"]
  }
}
```

Optionally add the hook script to `~/.claude/settings.json` for automatic startup context and exit gating:

```json
{
  "hooks": {
    "SessionStart": [{
      "matcher": "",
      "hooks": [{
        "type": "command",
        "command": "/path/to/gptqueue/scripts/check-queue.sh --startup"
      }]
    }],
    "Stop": [{
      "matcher": "",
      "hooks": [{
        "type": "command",
        "command": "/path/to/gptqueue/scripts/check-queue.sh --stop"
      }]
    }]
  }
}
```

### Any MCP client

The server speaks stdio MCP. Point your client at:

```bash
node /path/to/gptqueue/dist/mcp-server/index.js [agent-name]
```

Or set `GPTQ_AGENT_NAME` in the environment.

### Environment variables

| Variable | Default | Description |
|---|---|---|
| `REDIS_URL` | `redis://127.0.0.1:6379` | Redis connection URL (MCP server and PTY wrapper) |
| `GPTQ_AGENT_NAME` | _(none)_ | Pre-register with this agent name on startup |
| `GPTQ_QUEUE_BOUND` | `10` | Max messages per agent inbox |
| `REDIS_HOST` | `127.0.0.1` | Redis host (hook script only) |
| `REDIS_PORT` | `6379` | Redis port (hook script only) |

## PTY wrapper

The PTY wrapper lets you run any CLI (e.g. `claude`, `codex`) inside a PTY that monitors Redis for incoming messages and injects prompts when the process goes idle:

```bash
gptqueue-pty --agent alice --cmd claude
```

## How it works

1. **Registration** -- An agent calls `register_agent` with a name, role, and description. This writes to a Redis hash (`gptq:registry`) and starts a heartbeat (10s interval, 30s TTL).

2. **Discovery** -- Any agent (even unregistered) can call `list_agents` to see all registered agents and whether they're online.

3. **Messaging** -- `send_message` pushes to the target agent's Redis list (`gptq:q:`). A Lua script enforces the queue bound atomically. If the queue is full, the sender retries with exponential backoff (up to 10 attempts).

4. **Receiving** -- `receive_message` does a blocking pop (`BLPOP`) with a configurable timeout.

5. **Cleanup** -- `unregister_agent` removes the agent from the registry and deletes its queue, metadata, and heartbeat keys.

## License

MIT

## Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [rahulrajaram](https://github.com/rahulrajaram)
- **Source:** [rahulrajaram/gptqueue](https://github.com/rahulrajaram/gptqueue)
- **License:** MIT

Install and usage instructions live in the source repository linked above.

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** no
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** no
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/mcp-rahulrajaram-gptqueue
- Seller: https://agentstack.voostack.com/s/rahulrajaram
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.