Content
# Mesh Status MCP Server
Monitor your homelab agent mesh via MCP tools or CLI.
## What It Does
Provides 6 tools for monitoring a multi-agent homelab:
- **Agent health** — roles, workspaces, Docker containers
- **Docker services** — list, status, health checks, logs
- **Router V3** — routing stats, message routing, query distribution
- **Mesh overview** — everything at a glance
Works as both an **MCP server** (for AI agents) and a **CLI** (for humans).
## Install
```bash
pip install mesh-status-mcp
```
Or from source:
```bash
git clone https://github.com/Proto-labs-rnd/mesh-status-mcp.git
cd mesh-status-mcp
pip install -e ".[dev]"
```
## Quick Start
### CLI
```bash
# Full overview
mesh-status overview
# Agent details
mesh-status agents proto
# Container health
mesh-status health router-v3
# Route a query
mesh-status route "restart the database"
# Router stats
mesh-status stats
# Docker services
mesh-status services
# JSON output (works on all commands)
mesh-status --json overview
mesh-status --json agents
mesh-status --json services
mesh-status --json health router-v3
mesh-status --json route "restart the database"
mesh-status --json stats
```
### MCP Server (OpenClaw / Claude / etc.)
Add to your MCP config:
```json
{
"mcpServers": {
"mesh-status": {
"command": "python3",
"args": ["-m", "mesh_status.mcp_server"]
}
}
}
```
Or if installed via pip:
```json
{
"mcpServers": {
"mesh-status": {
"command": "mesh-status-mcp"
}
}
}
```
## Configuration
Create `mesh_status_config.yaml` or set environment variables:
```yaml
router:
url: "http://127.0.0.1:8905"
timeout: 5.0
retries: 2
retry_delay: 0.5
docker:
timeout: 10.0
max_containers_display: 20
log_tail_lines: 10
agents:
tachikoma:
role: "Orchestrator"
emoji: "🤖"
workspace: "workspace"
proto:
role: "R&D"
emoji: "🧪"
workspace: "workspace-labs"
log_level: "WARNING"
```
### Environment Variables
| Variable | Default | Description |
|----------|---------|-------------|
| `MESH_ROUTER_URL` | `http://127.0.0.1:8905` | Router V3 URL |
| `MESH_ROUTER_TIMEOUT` | `5.0` | Router timeout (seconds) |
| `MESH_LOG_LEVEL` | `WARNING` | Log level (DEBUG, INFO, WARNING) |
| `MESH_STATUS_CONFIG` | — | Path to config file |
### Config Search Order
1. `--config` CLI flag
2. `MESH_STATUS_CONFIG` env var
3. `./mesh_status_config.yaml`
4. `~/.config/mesh-status/config.yaml`
5. `/etc/mesh-status/config.yaml`
6. Built-in defaults
## Architecture
```
mesh_status/
├── __init__.py # Version
├── config.py # Configuration (YAML + env + defaults)
├── core.py # MeshStatus — shared business logic
├── docker_client.py # Docker CLI wrapper (timeout, retry, error types)
├── router_client.py # Router V3 HTTP client (retry, typed results)
├── mcp_server.py # MCP server entry point (6 tools via FastMCP)
└── cli.py # CLI entry point (argparse subcommands)
```
**Key design decisions:**
- `core.MeshStatus` is the single source of truth — both MCP and CLI use it
- Docker and Router clients have typed error hierarchies (`DockerError`, `RouterUnavailableError`)
- Every external call has timeout + retry with configurable attempts
- Graceful degradation: tools return informative messages instead of crashing
## Tools Reference
| Tool | Description | Args |
|------|-------------|------|
| `get_mesh_overview` | Full mesh overview | — |
| `get_agent_info` | Agent details | `agent_name` |
| `list_services` | Running Docker containers | — |
| `route_message` | Route via Router V3 | `query` |
| `get_router_stats` | Router statistics | — |
| `check_container_health` | Container health + logs | `container_name` |
## Development
```bash
pip install -e ".[dev]"
pytest
pytest --cov=mesh_status
```
## License
MIT
