terminal-progress-bar
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@terminal-progress-bar Create a progress bar named 'backup' with max 100"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
terminal-progress-bar
One progress, two interfaces: terminal for you, MCP for the AI.
Shared terminal progress bars for parallel scripts and processes. Track multiple jobs from different terminals or scripts and watch them update in real time.
Install
uv tool install -e .Or from a clone of this repository:
git clone https://github.com/you/terminal-progress-bar.git
cd terminal-progress-bar
uv tool install -e .Editable install (-e) keeps tpb linked to the source tree, so local changes take effect without reinstalling.
Related MCP server: Terminally MCP
Usage
Run tpb --help for an overview, or tpb <command> --help for command details
(e.g. tpb create --help).
Create a progress bar
tpb create backup-db 0 100 "Database backup"Update progress
tpb backup-db 35 # set absolute value
tpb backup-db +5 # increment
tpb backup-db -2 # decrement
tpb message backup-db "Importing users table"Finish or fail
tpb done backup-db "completed in 2m"
tpb error backup-db "connection timeout"List, status, remove
tpb # visual progress bars (Rich)
tpb list # plain text: slug, current, max, status, label
tpb status backup-db # machine-readable plain text output for one bar
tpb rm backup-db # remove a barMonitor in real time
tpb monitorThe monitor redraws the screen when any progress bar changes. Bars stay visible until removed with tpb rm. Press q to exit.
Storage
Each progress bar is stored as a separate JSON file:
~/.config/terminal-progress-bar/<slug>.jsonExample:
{
"slug": "backup-db",
"label": "Database backup",
"current": 35,
"max": 100,
"status": "active",
"status_text": "",
"created_at": "2026-07-30T12:00:00Z",
"updated_at": "2026-07-30T12:05:00Z"
}Bars are listed in creation order (created_at).
List output
tpb list prints one tab-separated line per bar:
import-data 25 100 active Import data
backup-db 100 100 done Database backupColumns: slug, current, max, status, label, and status_text (only when set).
Status output
tpb status <slug> prints plain key: value lines for scripting and AI agents:
slug: backup-db
label: Database backup
current: 35
max: 100
status: active
status_text:
created_at: 2026-07-30T12:00:00Z
updated_at: 2026-07-30T12:05:00ZMCP Server
The package includes an MCP server (tpb-mcp) for AI clients to manage progress bars programmatically over stdio.
Run
After install:
tpb-mcpFrom a clone without global install:
uv run tpb-mcpClient configuration
Example MCP client config:
{
"mcpServers": {
"terminal-progress-bar": {
"command": "tpb-mcp",
"args": []
}
}
}From the repository:
{
"mcpServers": {
"terminal-progress-bar": {
"command": "uv",
"args": ["run", "tpb-mcp"],
"cwd": "/path/to/terminal-progress-bar"
}
}
}Tools
Tool | Description |
| Create a progress bar |
| Set absolute progress value |
| Increment or decrement progress |
| Set status message below the bar |
| Mark as completed |
| Mark as failed |
| Remove a progress bar |
| List all bars (structured JSON) |
| Get one bar by slug |
Example flow: tpb_create → tpb_update / tpb_increment → tpb_message → tpb_done.
Tools return structured JSON (bar fields as dict). The human tpb monitor view updates automatically when bars change on disk.
Development
uv sync --group dev
uv run pytestLicense
MIT
Available Tools
9 toolstpb_createC
Create a new progress bar.
Inputs: slug (required), current (required), max_value (required), label. Returns: object
tpb_doneC
Mark a progress bar as completed.
Inputs: slug (required), status_text. Returns: object
tpb_errorC
Mark a progress bar as failed.
Inputs: slug (required), status_text. Returns: object
tpb_getB
Get structured status for a single progress bar.
Inputs: slug (required). Returns: object
tpb_incrementB
Increment or decrement progress by delta (use negative values to decrement).
Inputs: slug (required), delta (required). Returns: object
tpb_listA
List all progress bars in creation order.
Inputs: no named parameters. Returns: result
tpb_messageB
Set or update the status message shown below a progress bar.
Inputs: slug (required), text (required). Returns: object
tpb_removeC
Remove a progress bar.
Inputs: slug (required). Returns: object
tpb_updateB
Set the absolute progress value for a bar.
Inputs: slug (required), value (required). Returns: object
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 9 tools
Each tool has a clearly distinct purpose: create, update absolute value, increment delta, set message, mark done, mark error, remove, list, and get status. There is no overlap; even 'update' and 'increment' are differentiated by absolute vs. relative progress.
All tool names follow the same 'tpb_' prefix with a verb (create, update, increment, message, done, error, remove, list, get). The pattern is perfectly consistent and predictable.
With 9 tools, the server is well-scoped for managing progress bars. Each tool serves a necessary function in the lifecycle of a progress bar without unnecessary bloat.
The tool set covers the full lifecycle: create, update, increment, message, complete, error, remove, and query. There are no obvious gaps for a progress bar utility; all common operations are included.
Maintenance
Related MCP Connectors
MCP server for building and testing AI agents with multi-model experimentation and insights.
Official MCP server for Agentwork — delegate tasks to AI agents with human-in-the-loop
MCP server that lets your AI assistant build and deploy apps, hosting each one at a live URL.
MCP server for progressive tool usage at any scale (see https://klavis.ai)
Related MCP Servers
- AlicenseNot gradedqualityDmaintenanceAn MCP server that lets agents and humans monitor and control long-running processes, reducing copy-pasting between AI tools and enabling multiple agents to interact with the same process outputs.8MIT
- AlicenseNot gradedqualityDmaintenanceAn MCP server that gives AI assistants the ability to create, manage, and control terminal sessions through a safe, isolated tmux environment.1ISC
- AlicenseNot gradedqualityCmaintenanceMCP server that lets AI agents see and interact with terminal/CLI applications through virtual terminals and PNG screenshots.77 npmMIT
- AlicenseNot gradedqualityCmaintenanceMCP server that enables AI coding agents to communicate, share state, and coordinate work in real time via MCP tools or REST API.79 npm10MIT