Provides comprehensive Docker management capabilities including listing, monitoring, and controlling containers and Dockge stacks, reading and writing compose files, managing volumes and networks, and executing commands in containers.
Enables monitoring of OPNsense firewall status and restarting services through the OPNsense API.
Provides tools for checking ZFS pool health, managing datasets, retrieving alerts, and creating snapshots through the TrueNAS API.
Click on "Install 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., "@Homelab MCP Server check if my Docker containers are running and show CPU usage"
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.
A remote MCP (Model Context Protocol) server for managing homelab infrastructure. Provides Claude with tools to monitor and manage Docker containers, OPNsense firewall, TrueNAS storage, Proxmox virtualization, and Home Assistant service status.
4 Capability Levels: From read-only monitoring to full management control
Docker Management: List, monitor, control containers and Dockge stacks
OPNsense Integration: Monitor firewall status and restart services
TrueNAS Integration: Check pool health, manage datasets, create snapshots
Proxmox Integration: Monitor and manage VMs/containers, create snapshots
Home Assistant Integration: Monitor service health, entity states, configuration, and error logs
System Monitoring: CPU, memory, disk usage on the host
Related MCP server: InfraOps MCP Server
This software grants AI models direct control over your network infrastructure. Use with extreme caution.
AI Can Make Mistakes: Language models can misinterpret instructions, hallucinate requirements, or execute unintended actions. A simple request like "clean up unused containers" could result in critical services being stopped.
Destructive Actions Are Possible: At higher capability levels (3-4), the AI can:
Delete virtual machines and containers
Modify network configurations
Remove critical datasets or snapshots
Execute arbitrary commands in production systems
Overwrite docker-compose files, potentially causing data loss
No Undo Button: Once the AI executes a destructive action (deletes a VM, removes a dataset, stops a critical service), the damage is immediate and may be irreversible.
Network Security Implications: This server provides API access to your firewall, storage system, and virtualization platform. A compromised API key or misconfigured capability level could allow unauthorized control over your entire homelab.
Misunderstandings Happen: AI models may not fully understand your infrastructure's dependencies. Restarting one service could cascade into network-wide outages.
Start with Level 1 (Read-Only): Always begin with monitoring-only access and only increase capability levels when absolutely necessary.
Test in Development: If possible, test with non-production infrastructure first to understand how the AI interprets your requests.
Review Before Executing: At Level 2+, carefully review what actions the AI plans to take before confirming execution.
Keep Backups: Ensure you have recent backups of all critical systems before granting Level 3+ access.
Rotate Credentials: Regularly rotate API keys and OAuth credentials. Treat them as highly sensitive.
Monitor Logs: Watch the container logs to see what actions are being executed in real-time.
Use Network Segmentation: Consider running this server in a restricted network segment with limited access to critical infrastructure.
BY USING THIS SOFTWARE, YOU ACKNOWLEDGE THAT YOU UNDERSTAND THESE RISKS AND ACCEPT FULL RESPONSIBILITY FOR ANY ACTIONS TAKEN BY THE AI, INCLUDING DATA LOSS, SERVICE DISRUPTION, OR SECURITY INCIDENTS.
Docker and Docker Compose installed on target host (Wharf)
OPNsense API credentials (optional)
TrueNAS API key (optional)
Node.js 20+ (for local development)
# Clone or copy the project to your host
cd homelab-mcp
# Copy example environment file
cp .env.example .env
# Generate a secure API key
openssl rand -hex 32
# Edit .env and add your credentials
nano .envEdit .env with your settings:
CAPABILITY_LEVEL=1 # Start with level 1 (read-only)
API_KEY=your-api-key-here # Use the generated key
PORT=3005
# OPNsense (optional)
OPNSENSE_HOST=10.0.0.1
OPNSENSE_API_KEY=your-key
OPNSENSE_API_SECRET=your-secret
# TrueNAS (optional)
TRUENAS_HOST=10.0.0.105
TRUENAS_API_KEY=your-key
# Proxmox (optional)
PROXMOX_HOST=10.0.0.2
PROXMOX_TOKEN_ID=root@pam!mytoken
PROXMOX_TOKEN_SECRET=your-secret
# Home Assistant (optional)
HOME_ASSISTANT_HOST=10.0.0.103
HOME_ASSISTANT_PORT=8123
HOME_ASSISTANT_TOKEN=your-long-lived-token
HOME_ASSISTANT_USE_HTTPS=false# Build TypeScript
npm install
npm run build
# Build Docker image
docker compose build
# Start the server
docker compose up -d
# Check logs
docker compose logs -fAdd to your Claude Desktop MCP settings:
{
"mcpServers": {
"homelab": {
"command": "node",
"args": ["/path/to/homelab-mcp/dist/index.js"],
"env": {
"CAPABILITY_LEVEL": "1",
"API_KEY": "your-api-key-here",
"OPNSENSE_HOST": "10.0.0.1",
"OPNSENSE_API_KEY": "your-key",
"OPNSENSE_API_SECRET": "your-secret",
"TRUENAS_HOST": "10.0.0.105",
"TRUENAS_API_KEY": "your-key",
"PROXMOX_HOST": "10.0.0.2",
"PROXMOX_TOKEN_ID": "root@pam!mytoken",
"PROXMOX_TOKEN_SECRET": "your-secret",
"HOME_ASSISTANT_HOST": "10.0.0.103",
"HOME_ASSISTANT_PORT": "8123",
"HOME_ASSISTANT_TOKEN": "your-long-lived-token",
"HOME_ASSISTANT_USE_HTTPS": "false"
}
}
}
}For accessing the MCP server from Claude Chat (web interface), deploy with HTTP transport:
Set environment variables in .env:
PORT=3000
API_KEY=your-generated-key
CAPABILITY_LEVEL=1Deploy the container:
docker compose up -dConfigure reverse proxy (e.g., Traefik, Pangolin, nginx) to route mcp.example.com to http://localhost:3000
Add DNS record pointing mcp.example.com to your server
In Claude Chat, add the MCP server:
URL: https://mcp.example.com/mcp
Authentication: Bearer token
Token: Your API_KEY value
Claude Chat requires OAuth 2.0 for custom connectors. This server supports the Client Credentials flow.
Generate OAuth credentials:
# Generate client ID
openssl rand -hex 32
# Generate client secret
openssl rand -hex 32Add to .env:
OAUTH_CLIENT_ID=your-generated-client-id
OAUTH_CLIENT_SECRET=your-generated-client-secretIn Claude Chat, add the connector:
Name: Homelab
Remote MCP server URL: https://mcp.example.com/mcp
OAuth Client ID: Your generated client ID
OAuth Client Secret: Your generated client secret
The server will issue access tokens valid for 1 hour. Claude Chat handles token refresh automatically.
When running in HTTP mode:
Endpoint | Method | Auth | Description |
| GET | No | Health check, returns status and capability level |
| POST | No | OAuth 2.0 token endpoint |
| POST | Yes | MCP protocol endpoint |
| POST | Yes | Alias for /mcp |
# Test health endpoint
curl https://mcp.example.com/health
# Get an access token
curl -X POST https://mcp.example.com/oauth/token \
-H "Content-Type: application/x-www-form-urlencoded" \
-d "grant_type=client_credentials&client_id=YOUR_CLIENT_ID&client_secret=YOUR_CLIENT_SECRET"
# Use the token
curl https://mcp.example.com/mcp \
-H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
-H "Content-Type: application/json" \
-d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'Level | Name | Capabilities |
1 | Monitor | Read-only: container status, logs, stats, system info, service health |
2 | Operate | Level 1 + start/stop/restart containers and services |
3 | Configure | Level 2 + read compose files, configs, volumes, networks |
4 | Manage | Level 3 + write configs, create/remove containers, exec commands |
Recommendation: Start with Level 1 and increase as needed.
docker_list_containers - List all containers
docker_container_logs - Get container logs
docker_container_stats - Get container CPU/memory stats
system_info - Get host system info
opnsense_status - Get OPNsense status
truenas_status - Get TrueNAS pool status
truenas_alerts - Get TrueNAS alerts
proxmox_status - Get Proxmox cluster status
proxmox_list_vms - List all VMs and containers
proxmox_vm_status - Get VM/container status
home_assistant_status - Get Home Assistant version and entity counts
home_assistant_list_entities - List all entities (lights, switches, sensors)
home_assistant_get_entity - Get specific entity state and attributes
docker_restart_container - Restart a container
docker_start_container - Start a container
docker_stop_container - Stop a container
opnsense_service_restart - Restart OPNsense service
proxmox_start_vm - Start a VM/container
proxmox_stop_vm - Stop a VM/container
proxmox_shutdown_vm - Gracefully shutdown a VM/container
proxmox_reboot_vm - Reboot a VM/container
docker_read_compose - Read docker-compose.yml
docker_list_volumes - List Docker volumes
docker_list_networks - List Docker networks
docker_inspect_container - Inspect container details
truenas_list_datasets - List ZFS datasets
truenas_dataset_info - Get dataset details
proxmox_vm_config - Get VM/container configuration
proxmox_list_storage - List Proxmox storage
proxmox_list_nodes - List cluster nodes
home_assistant_get_config - Get Home Assistant configuration
home_assistant_error_log - Get error log
docker_write_compose - Write docker-compose.yml
docker_compose_up - Deploy a stack
docker_compose_down - Remove a stack
docker_exec - Execute command in container
truenas_create_snapshot - Create ZFS snapshot
proxmox_create_snapshot - Create VM/container snapshot
proxmox_delete_vm - Delete a VM/container
# Install dependencies
npm install
# Run in development mode
npm run dev
# Build
npm run build
# Type check
npx tsc --noEmitThe API key should be kept secret and rotated periodically
Start with the lowest capability level you need
For Level 4, the /opt/stacks mount must be :rw instead of :ro
The container requires access to the Docker socket for container management
OPNsense and TrueNAS APIs use self-signed certificates by default
# Check logs
docker compose logs homelab-mcp
# Common issues:
# - Missing API_KEY in .env
# - Invalid CAPABILITY_LEVEL (must be 1-4)
# - Docker socket not accessible# Test OPNsense API
curl -k -u "key:secret" https://10.0.0.1/api/core/system/status
# Test TrueNAS API
curl -k -H "Authorization: Bearer YOUR_KEY" https://10.0.0.105/api/v2.0/system/info
# Test Home Assistant API
curl -H "Authorization: Bearer YOUR_TOKEN" http://10.0.0.103:8123/api/
# Check network connectivity from container
docker exec homelab-mcp ping 10.0.0.1If you need Level 4 (write access to stacks), update the volume mount:
volumes:
- /opt/stacks:/opt/stacks:rw # Change from :ro to :rwMIT
Issues and pull requests welcome!
Get recent logs from a container
| Name | Required | Description | Default |
|---|---|---|---|
| container | Yes | Container name or ID | |
| lines | No | Number of lines to return (default: 50, max: 500) | |
| since | No | Only logs since timestamp, e.g., "1h", "30m" | |
| filter | No | Regex pattern to filter log lines (e.g., "error|warn|fail") |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries full burden for behavioral disclosure. 'Get recent logs' implies a read-only operation, but it doesn't specify permissions needed, whether this affects container performance, rate limits, or what format/log level the logs return. For a tool that interacts with running containers, more behavioral context would be helpful.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise at just 5 words, front-loading the core purpose with zero wasted words. Every word earns its place, making it easy for an agent to quickly understand the tool's function.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool with 4 parameters, no annotations, and no output schema, the description is insufficiently complete. It doesn't explain what the logs contain, their format, whether they include timestamps, or how 'recent' is defined. Given the complexity of container logging and lack of structured metadata, more context would help agents use this tool effectively.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the input schema already documents all four parameters thoroughly. The description adds no additional parameter semantics beyond what's in the schema - it doesn't explain relationships between parameters or provide usage examples. Baseline 3 is appropriate when schema does the heavy lifting.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'Get' and resource 'recent logs from a container', making the purpose immediately understandable. However, it doesn't differentiate from potential sibling tools like 'docker_container_stats' which might also provide container information, though those appear focused on different aspects (stats vs logs).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives. While sibling tools like 'docker_list_containers' and 'docker_container_stats' exist, there's no mention of when to choose logs over stats or how this relates to other container monitoring tools. No prerequisites or exclusions are stated.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get CPU/memory/network stats for a container
| Name | Required | Description | Default |
|---|---|---|---|
| container | Yes | Container name or ID |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of behavioral disclosure. It states what the tool does but lacks details on traits like whether it requires specific permissions, if it's read-only or has side effects, rate limits, or what the output format looks like (e.g., real-time vs. snapshot). This is a significant gap for a stats tool with zero annotation coverage.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, efficient sentence that front-loads the core purpose without any wasted words. It's appropriately sized for a simple tool, making it easy to scan and understand quickly.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity (stats retrieval with no output schema) and lack of annotations, the description is incomplete. It doesn't explain return values, error conditions, or behavioral context, which are crucial for an agent to use it correctly. This falls short of what's needed for adequate contextual understanding.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, with the single parameter 'container' well-documented in the schema as 'Container name or ID'. The description adds no additional meaning beyond this, such as examples or constraints, so it meets the baseline of 3 where the schema does the heavy lifting.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb ('Get') and resource ('CPU/memory/network stats for a container'), making the purpose specific and understandable. However, it doesn't explicitly differentiate from sibling tools like 'docker_container_logs' or 'proxmox_vm_status', which might also provide performance metrics in different contexts, preventing a perfect score.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives. It doesn't mention prerequisites (e.g., container must be running), exclusions, or comparisons to siblings like 'docker_list_containers' for general info or 'system_info' for broader stats, leaving usage context implied at best.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List all Docker containers with their status
| Name | Required | Description | Default |
|---|---|---|---|
| all | No | Include stopped containers (default: true) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of behavioral disclosure. It states the action ('List') but doesn't describe what the output looks like (e.g., format, fields), whether it requires Docker daemon access, or any rate limits or permissions needed. This leaves significant gaps for an agent to understand the tool's behavior.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, efficient sentence that directly states the tool's purpose without unnecessary words. It's front-loaded with the core action and resource, making it easy to parse quickly.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the lack of annotations and output schema, the description is incomplete. It doesn't explain the return format (e.g., list of container objects with IDs, names, statuses), which is critical for a list operation. For a tool with no structured behavioral hints, this leaves the agent with insufficient context.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 100% description coverage, with the single parameter 'all' clearly documented in the schema. The description doesn't add any parameter-specific information beyond what the schema provides, so it meets the baseline score of 3 for high schema coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb ('List') and resource ('Docker containers') with scope ('all'), making the purpose immediately understandable. However, it doesn't differentiate from potential sibling tools like 'docker_container_stats' or 'docker_container_logs' that also operate on containers, which prevents a perfect score.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives. It doesn't mention when to prefer this over sibling tools like 'docker_container_stats' for monitoring or 'docker_container_logs' for debugging, nor does it specify prerequisites or exclusions for usage.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get detailed state and attributes of a specific Home Assistant entity
| Name | Required | Description | Default |
|---|---|---|---|
| entity_id | Yes | Entity ID (e.g., "light.living_room", "switch.bedroom") |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries full burden but offers minimal behavioral context. It states this is a 'get' operation but doesn't disclose whether it's read-only, requires authentication, has rate limits, returns structured data, or handles errors. The description is functionally correct but lacks operational transparency.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, efficient sentence that communicates the core functionality without unnecessary words. It's appropriately sized for a simple retrieval tool and front-loads the essential information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple single-parameter retrieval tool with good schema coverage but no annotations or output schema, the description is minimally adequate. It states what the tool does but lacks important context about when to use it, what the output contains, and behavioral characteristics that would help an agent use it effectively.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The description doesn't add parameter information beyond what's already in the schema (which has 100% coverage). It mentions 'a specific Home Assistant entity' which aligns with the entity_id parameter, but provides no additional syntax examples, format requirements, or semantic context beyond the schema's description.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('Get detailed state and attributes') and resource ('of a specific Home Assistant entity'), making the purpose immediately understandable. However, it doesn't explicitly differentiate from its sibling 'home_assistant_list_entities' beyond the singular vs. plural distinction.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives like 'home_assistant_list_entities' or other monitoring tools. It doesn't mention prerequisites (e.g., needing an entity ID first) or contextual constraints for selecting this specific retrieval method.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List all Home Assistant entities (lights, switches, sensors, etc.)
| Name | Required | Description | Default |
|---|---|---|---|
| domain | No | Optional: Filter by domain (e.g., "light", "switch", "sensor") |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden. It states the action ('List all Home Assistant entities') but doesn't disclose behavioral traits such as whether this is a read-only operation, potential rate limits, authentication requirements, or what the output format looks like. It adds minimal context beyond the basic action.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, efficient sentence that directly states the tool's purpose with no wasted words. It is appropriately sized and front-loaded, making it easy to understand at a glance.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's low complexity (one optional parameter) and no output schema, the description is minimally adequate. It covers the basic purpose but lacks details on behavioral aspects like output format or operational constraints. Without annotations, it should provide more context for a complete understanding.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 100% description coverage, with one optional parameter 'domain' documented as filtering by domain. The description doesn't add any parameter semantics beyond what the schema provides, such as explaining the filter behavior in more detail. With high schema coverage, the baseline score of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb ('List') and resource ('all Home Assistant entities') with examples of entity types ('lights, switches, sensors, etc.'). It distinguishes from siblings like 'home_assistant_get_entity' by indicating it lists all entities rather than retrieving a specific one. However, it doesn't explicitly differentiate from other list tools like 'docker_list_containers' beyond the resource scope.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage for listing entities, but provides no explicit guidance on when to use this tool versus alternatives. It doesn't mention when to use 'home_assistant_get_entity' for single entities or other sibling tools for different resources. The context is clear but lacks comparative guidance.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get Home Assistant version, entity count, and available domains
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of behavioral disclosure. It states what information is retrieved but does not describe how the tool behaves—e.g., whether it requires authentication, has rate limits, returns data in a specific format, or if it's a read-only operation. This lack of detail makes it difficult for an agent to anticipate the tool's behavior beyond the basic output.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, efficient sentence that directly states the tool's function without any redundant information. It is front-loaded with the key action ('Get') and lists the specific data points retrieved, making it easy to parse and understand quickly. Every word contributes to clarifying the tool's purpose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity (simple status retrieval with no parameters) and the lack of annotations and output schema, the description is incomplete. It specifies what data is fetched but does not cover behavioral aspects like authentication needs, error handling, or output format, which are crucial for an agent to use the tool effectively in a real-world context.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has zero parameters, and the input schema has 100% description coverage (though empty). The description does not need to add parameter semantics, as there are none to document. It appropriately focuses on the tool's purpose without unnecessary parameter details, meeting the baseline for tools with no parameters.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's function with specific verbs ('Get') and resources ('Home Assistant version, entity count, and available domains'), making the purpose immediately understandable. It distinguishes itself from siblings like 'home_assistant_get_entity' and 'home_assistant_list_entities' by focusing on system status rather than individual entities or entity listings. However, it doesn't explicitly contrast with other status tools like 'opnsense_status' or 'proxmox_status', which slightly limits differentiation.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives. It does not mention prerequisites, context for usage, or comparisons to sibling tools such as 'system_info' or other status-checking tools in the list. This leaves the agent without explicit direction on tool selection in relevant scenarios.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get OPNsense firewall/gateway status
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden of behavioral disclosure. It states the tool 'Get[s]' status, implying a read-only operation, but does not specify details like authentication needs, rate limits, or what the status includes (e.g., uptime, load, errors). For a tool with zero annotation coverage, this is a significant gap in transparency.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, efficient sentence: 'Get OPNsense firewall/gateway status'. It is front-loaded with the core purpose, has no wasted words, and is appropriately sized for a simple status-checking tool.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's low complexity (0 parameters, no output schema, no annotations), the description is minimally adequate. It states what the tool does but lacks details on behavior, output format, or integration context. Without annotations or output schema, more context on what 'status' entails would improve completeness.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has 0 parameters with 100% schema description coverage, so the schema fully documents the inputs. The description does not add parameter information, which is acceptable as there are no parameters to explain. Baseline 4 is appropriate for zero-parameter tools.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose as 'Get OPNsense firewall/gateway status', specifying the verb 'Get' and the resource 'OPNsense firewall/gateway status'. It distinguishes from siblings like 'proxmox_status' or 'truenas_status' by focusing on OPNsense, though it doesn't explicitly differentiate usage from similar status-checking tools.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus alternatives. The description does not mention prerequisites, context, or exclusions, such as when to choose this over other status tools like 'system_info' or 'home_assistant_status'. It lacks explicit usage instructions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List all Proxmox VMs and containers across all nodes
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of behavioral disclosure. It states what the tool does but lacks critical behavioral details: it doesn't mention authentication requirements, rate limits, error handling, pagination (if applicable for large result sets), or the format/structure of the returned list. For a tool that likely interacts with a production system, this is a significant gap.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, clear sentence that efficiently conveys the core functionality without any wasted words. It's front-loaded with the essential information ('List all Proxmox VMs and containers') and adds necessary scope clarification ('across all nodes'). Every word earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity (zero parameters, no output schema) and the absence of annotations, the description provides the minimum viable information about what the tool does. However, for a tool that likely returns structured data about system resources, the lack of output schema means the description should ideally hint at the return format or data structure, which it doesn't. It's adequate but leaves gaps about what the agent can expect from the response.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has zero parameters, and schema description coverage is 100% (though trivial since there are no parameters). The description appropriately doesn't discuss parameters since none exist. It correctly focuses on the tool's function without unnecessary parameter explanations, meeting the baseline for zero-parameter tools.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('List') and the resource ('all Proxmox VMs and containers across all nodes'), making the purpose immediately understandable. It distinguishes from siblings like 'proxmox_status' and 'proxmox_vm_status' by focusing specifically on enumeration rather than status checking. However, it doesn't explicitly differentiate from potential non-sibling alternatives like filtered listing tools.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is provided on when to use this tool versus alternatives. While the description implies it's for comprehensive listing, there's no mention of when to choose this over more specific tools like 'proxmox_vm_status' for individual VM details or filtered approaches. The agent must infer usage context solely from the tool name and description.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get Proxmox cluster status and node information
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries full burden for behavioral disclosure. It states it 'gets' information, implying a read-only operation, but doesn't clarify aspects like authentication requirements, rate limits, error conditions, or what specific 'status and node information' includes (e.g., health metrics, uptime). For a tool with zero annotation coverage, this is a significant gap in transparency.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, efficient sentence that front-loads the core purpose with zero wasted words. It directly answers 'what does this tool do?' without fluff or redundancy, making it optimally concise and well-structured for quick comprehension.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity (0 parameters, no output schema, no annotations), the description is minimally complete—it states what the tool does. However, it lacks details on return values (since no output schema exists) and behavioral context, which are needed for full agent understanding. It's adequate but leaves gaps in a low-complexity scenario.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 0 parameters with 100% coverage, so no parameter documentation is needed. The description appropriately doesn't discuss parameters, focusing instead on the tool's purpose. A baseline of 4 is applied since the schema fully handles parameters, and the description doesn't add unnecessary param details.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'Get' and the resource 'Proxmox cluster status and node information', making the purpose immediately understandable. It distinguishes from siblings like 'proxmox_list_vms' and 'proxmox_vm_status' by focusing on cluster-wide status rather than VMs. However, it doesn't explicitly differentiate scope (e.g., 'cluster-wide' vs 'node-specific'), which prevents a perfect score.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives. It doesn't mention when to choose this over 'proxmox_list_vms' for VM details or 'system_info' for general system status, nor does it specify prerequisites like cluster connectivity. This leaves the agent without contextual usage cues.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get detailed status of a specific Proxmox VM or container
| Name | Required | Description | Default |
|---|---|---|---|
| node | Yes | Node name | |
| vmid | Yes | VM/Container ID | |
| type | Yes | VM type: qemu (virtual machine) or lxc (container) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden of behavioral disclosure. It states the tool retrieves 'detailed status' but doesn't specify what that includes (e.g., CPU/memory usage, state, uptime), whether it's a read-only operation, potential errors, or rate limits. For a tool with no annotations, this leaves significant gaps in understanding its behavior and constraints.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, efficient sentence that directly states the tool's purpose without unnecessary words. It is front-loaded with the core action ('Get detailed status'), making it easy to parse. Every part of the sentence earns its place by specifying the resource type and scope.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the complexity (a tool with 3 required parameters and no annotations) and lack of output schema, the description is incomplete. It doesn't explain what 'detailed status' entails in the return values, potential error conditions, or how it differs from other status tools. For a tool that likely returns structured data, more context is needed to guide effective use.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, with clear descriptions for all three parameters (node, vmid, type). The description adds no additional parameter semantics beyond what's in the schema, such as examples or format details. According to the rules, with high schema coverage (>80%), the baseline is 3 even without param info in the description, which is appropriate here.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb ('Get') and resource ('detailed status of a specific Proxmox VM or container'), making the purpose unambiguous. It distinguishes from sibling tools like 'proxmox_list_vms' by focusing on a single VM/container rather than listing all. However, it doesn't explicitly differentiate from other status tools like 'proxmox_status' or 'system_info', which slightly limits sibling differentiation.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives. It doesn't mention prerequisites, such as needing node/vmid/type parameters, or compare to siblings like 'proxmox_list_vms' for broader queries or 'proxmox_status' for overall system status. Without such context, users must infer usage from the tool name and parameters alone.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get host system information (disk, memory, CPU usage)
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries full burden. It states it 'gets' information, implying a read-only operation, but doesn't disclose behavioral traits like whether it requires permissions, has rate limits, returns real-time vs. cached data, or what format the output is in. This is a significant gap for a tool with zero annotation coverage.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, efficient sentence that front-loads the purpose ('Get host system information') and adds specifics ('disk, memory, CPU usage') without unnecessary words. Every part earns its place, making it highly concise and well-structured.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no annotations, no output schema, and a simple input schema with 0 parameters, the description is incomplete. It lacks details on output format, behavioral context (e.g., permissions, data freshness), and doesn't help differentiate from sibling tools. For a system info tool, more context is needed to guide effective use.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has 0 parameters, and schema description coverage is 100%, so there are no parameters to document. The description doesn't need to add parameter semantics, and it appropriately doesn't mention any. A baseline of 4 is applied as per rules for zero parameters.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb ('Get') and resource ('host system information') with specific components listed (disk, memory, CPU usage). However, it doesn't explicitly differentiate from sibling tools like 'docker_container_stats' or 'proxmox_status', which also provide system-related information but for different scopes.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives. It doesn't mention prerequisites, exclusions, or compare to sibling tools that might offer similar or overlapping functionality, such as 'docker_container_stats' for container-level metrics or 'proxmox_status' for hypervisor status.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get active TrueNAS alerts
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries full burden for behavioral disclosure. While 'Get' implies a read operation, the description doesn't specify whether this retrieves current alerts only, historical alerts, or both. It also doesn't mention authentication requirements, rate limits, or what format the alerts come in (e.g., severity levels, timestamps).
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is perfectly concise at just 4 words: 'Get active TrueNAS alerts'. Every word earns its place - verb, scope ('active'), system ('TrueNAS'), and resource ('alerts'). There's zero waste or redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple read-only tool with no parameters and no output schema, the description is minimally adequate. However, without annotations or output schema, it should ideally specify what 'active' means (e.g., unacknowledged, current, within last 24 hours) and what information the alerts contain. The absence of output schema means the description should compensate by hinting at return format.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has 0 parameters with 100% schema description coverage, so the schema already fully documents the absence of parameters. The description doesn't need to explain any parameters, and it correctly doesn't mention any. The baseline for 0 parameters with full schema coverage is 4.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'Get' and the resource 'active TrueNAS alerts', making the purpose immediately understandable. However, it doesn't distinguish this tool from potential siblings like 'truenas_status' - both could involve retrieving TrueNAS information, though one is specifically about alerts while the other about general status.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance about when to use this tool versus alternatives. With siblings like 'truenas_status' that also retrieve TrueNAS information, there's no indication whether this tool should be used for real-time alert monitoring while 'truenas_status' provides general system health, or if they serve different purposes entirely.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get TrueNAS pool health and system status
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of behavioral disclosure. It states what the tool does but doesn't describe how it behaves—such as whether it requires authentication, has rate limits, returns real-time or cached data, or what format the output takes. This leaves significant gaps in understanding the tool's operational characteristics.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single, efficient sentence that directly states the tool's purpose without any fluff or redundant information. It's front-loaded with the core functionality, making it easy to parse and understand quickly.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's simplicity (0 parameters, no output schema, no annotations), the description is minimally adequate. It tells what the tool does but lacks details on behavior, output format, or usage context. For a status-checking tool with no structured metadata, more guidance on what 'health and system status' entails would improve completeness.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has 0 parameters, and the schema description coverage is 100%, so there are no parameters to document. The description doesn't need to add parameter semantics, and it appropriately doesn't mention any. A baseline score of 4 is applied as it meets the expectation for a parameterless tool without unnecessary elaboration.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose with a specific verb ('Get') and resource ('TrueNAS pool health and system status'), making it immediately understandable. However, it doesn't explicitly differentiate from its sibling 'truenas_alerts', which might provide overlapping or related information about TrueNAS system status.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives. It doesn't mention when it's appropriate to use 'truenas_status' over 'truenas_alerts' or other system monitoring tools like 'system_info', 'proxmox_status', or 'opnsense_status', leaving the agent without context for tool selection.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections. Dates show when Glama detected each change.
docker_container_logsdocker_container_statsdocker_list_containershome_assistant_get_entityhome_assistant_list_entitieshome_assistant_statusopnsense_statusproxmox_list_vmsproxmox_statusproxmox_vm_statussystem_infotruenas_alertstruenas_statusEach tool has a clearly distinct purpose targeting specific resources and actions, such as docker_container_logs vs. docker_container_stats, home_assistant_get_entity vs. home_assistant_list_entities, and proxmox_list_vms vs. proxmox_vm_status. There is no ambiguity or overlap in functionality, making it easy for an agent to select the correct tool.
All tool names follow a consistent verb_noun pattern with clear prefixes for each domain (e.g., docker_, home_assistant_, proxmox_, system_, truenas_). The naming is uniform across the set, using snake_case throughout without any deviations or mixed conventions.
With 13 tools, the server is well-scoped for monitoring a homelab environment, covering key areas like Docker, Home Assistant, Proxmox, TrueNAS, OPNsense, and system info. Each tool serves a distinct monitoring purpose, and the count is appropriate without being excessive or insufficient.
The tool set provides comprehensive read-only monitoring coverage for homelab components, including status, lists, and detailed views. Minor gaps exist, such as no control actions (e.g., starting/stopping containers or VMs) or deeper diagnostic tools, but agents can effectively monitor the environment with the available tools.
Unclaimed servers have limited discoverability.
If you are the server author, to access and configure the admin panel.
Uptime, SSL, DNS and domain monitoring you can talk to from Claude or any MCP client.
Manage hosts, redirects, SSL, and traffic analytics from Claude and other AI assistants.
Provides capabilities that let LLM agents perform a range of infrastructure management tasks.
Monitoring + status pages set up by talking to Claude. Auto-detects 30+ SDKs and your URLs.
We provide all the information about MCP servers via our MCP API.
curl -X GET 'https://glama.ai/api/mcp/v1/servers/bshandley/homelab-mcp'
If you have feedback or need assistance with the MCP directory API, please join our Discord server