Manages GNOME Boxes virtual machines through libvirt/virsh, providing VM lifecycle operations (start, stop, reboot, suspend, resume), snapshot management (create, list, revert, delete), and VM discovery with detailed information.
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., "@boxes-mcp list all VMs"
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 lightweight Model Context Protocol (MCP) server that enables Claude Code to manage GNOME Boxes virtual machines through libvirt/virsh. Provides safe, reversible VM operations with comprehensive snapshot management.
🖥️ VM Lifecycle Management - Start, stop, reboot, suspend, and resume VMs
📸 Snapshot Operations - Create, list, revert, and delete VM snapshots
🔍 VM Discovery - List and inspect all VMs with detailed information
🔒 Safe Operations - Storage preservation by default, no destructive actions
🎯 GNOME Boxes Compatible - Works seamlessly with GNOME Boxes VMs
⚡ Fast & Lightweight - Minimal overhead, direct virsh integration
Related MCP server: libvirt-mcp-server
Ubuntu 22.04/24.04 (or compatible Linux distribution)
libvirt-daemon-system, qemu-kvm installed
Node.js 18+ and npm
User in libvirt and kvm groups
# Install dependencies
sudo apt install -y libvirt-daemon-system qemu-kvm virt-manager
# Add your user to required groups
sudo usermod -aG libvirt,kvm "$USER"
newgrp libvirt# Clone the repository
git clone https://github.com/your-org/boxes-mcp.git
cd boxes-mcp
# Install dependencies
npm install
# Build the project
npm run build
# Run tests
npm testAdd to your Claude Code config (~/.claude/config.json):
{
"mcpServers": {
"boxes": {
"command": "node",
"args": ["/absolute/path/to/boxes-mcp/dist/src/index.js"],
"env": {
"LIBVIRT_URI": "qemu:///system"
}
}
}
}Tool | Description | Parameters |
| List all VMs | - |
| Get VM details |
|
| Start a VM |
|
| Shutdown VM (graceful) |
|
| Reboot a VM |
|
| Suspend a VM |
|
| Resume suspended VM |
|
| Remove VM (keeps storage) |
|
| Get SPICE/VNC address |
|
Tool | Description | Parameters |
| List VM snapshots |
|
| Create snapshot |
|
| Revert to snapshot |
|
| Delete snapshot |
|
User: "List all my VMs"
Claude: [Uses boxes.list tool]
User: "Start ubuntu-24.04"
Claude: [Uses boxes.start with nameOrUuid="ubuntu-24.04"]
User: "Create a snapshot called 'before-update' for my fedora VM"
Claude: [Uses boxes.snapshots.create]# Run the MCP server
LIBVIRT_URI=qemu:///system node dist/src/index.jsboxes-mcp/
├── src/
│ ├── index.ts # MCP server entry point
│ ├── libvirt.ts # virsh operations & parsers
│ ├── exec.ts # Safe command execution
│ ├── *.test.ts # Unit tests
├── systemd/
│ └── boxes-mcp.service # Systemd user service
├── dist/ # Compiled JavaScript
├── coverage/ # Test coverage reports
├── package.json
├── tsconfig.json
└── vitest.config.ts# Run all tests
npm test
# Run tests in watch mode
npm run test:watch
# Generate coverage report
npm run test:coverageTest Coverage: 33 tests, 100% passing
exec.ts: 100% statements
libvirt.ts: 81.3% statements, 92.85% branches
Comprehensive unit and integration tests
# Build TypeScript
npm run build
# Watch mode for development
npm run devInstall as a user service for automatic startup:
mkdir -p ~/.config/systemd/user
cp systemd/boxes-mcp.service ~/.config/systemd/user/
sed -i "s|%h/projects/virtmcp|$HOME/boxes-mcp|g" ~/.config/systemd/user/boxes-mcp.service
systemctl --user daemon-reload
systemctl --user enable --now boxes-mcp
journalctl --user -fu boxes-mcp✅ Sandboxed Execution: Uses Node.js execFile with timeout and buffer limits
✅ No Arbitrary Commands: Only predefined virsh operations allowed
✅ Storage Preservation: VM storage not deleted by default
✅ LIBVIRT_URI Isolation: Respects environment-specified libvirt connection
⚠️ Permissions Required: User must have libvirt group membership
⚠️ Network Exposure: Not designed for remote access without additional security
# Check libvirt URI
virsh -c qemu:///system list --all
virsh -c qemu:///session list --all
# Verify permissions
groups # Should include 'libvirt' and 'kvm'# Re-add to groups and re-login
sudo usermod -aG libvirt,kvm "$USER"
# Then logout/login or:
newgrp libvirtOpen virt-manager and check which connection your VMs use:
System connection: qemu:///system
User session: qemu:///session
Set LIBVIRT_URI environment variable accordingly.
VM creation via virt-install integration
Network management (virsh net-list, port forwarding)
Storage pool information (virsh vol-list)
VM import from OVA/QCOW2
Remote libvirt connection support
Performance metrics and monitoring
Contributions welcome! Please read CONTRIBUTING.md for guidelines.
Fork the repository
Create a feature branch (git checkout -b feature/amazing-feature)
Run tests (npm test)
Commit changes (git commit -m 'Add amazing feature')
Push to branch (git push origin feature/amazing-feature)
Open a Pull Request
This project is licensed under the MIT License - see the LICENSE file for details.
Built for Claude Code
Integrates with libvirt virtualization API
Issues: GitHub Issues
Discussions: GitHub Discussions
Documentation: Project Wiki
Made with ❤️ for the Claude Code community
Get SPICE/VNC display address for VM (useful to open viewer)
| Name | Required | Description | Default |
|---|---|---|---|
| nameOrUuid | Yes | Domain name or UUID |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so description carries full burden. It indicates a read operation but does not disclose permissions needed or return format, which is a 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?
Single sentence front-loads the main action with no wasted words. Perfectly concise.
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 tool with one parameter and no output schema, the description is adequate but could specify the return format for better 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?
Schema coverage is 100% with one parameter described. The description adds no extra meaning beyond the schema's own description, so baseline score applies.
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 retrieves a SPICE/VNC display address for a VM, with a specific use case. It distinguishes from siblings like boxes.info by being address-specific.
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 opening a viewer but does not explicitly state when not to use or mention alternatives. Context is clear but lacks exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get detailed domain info
| Name | Required | Description | Default |
|---|---|---|---|
| nameOrUuid | Yes | Domain name or UUID |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided. Description does not disclose any behavioral traits such as side effects, required permissions, or rate limits. While a read-only operation is implied, it is not stated, and the description adds no value beyond the schema.
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?
Description is a single concise sentence that efficiently conveys the tool's purpose. No unnecessary words, but it lacks structure and could benefit from additional context without significant verbosity.
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 (1 param, no output schema, no annotations), the description vaguely covers what the tool does. However, it fails to specify the format or content of the returned 'detailed domain info', which is necessary for an agent to process results correctly.
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 coverage is 100%, so baseline is 3. Description adds no additional meaning beyond the schema's 'Domain name or UUID'. No examples, constraints, or format details are provided, but the schema already describes the parameter adequately.
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?
Description uses specific verb 'Get' and resource 'detailed domain info', clearly indicating retrieval of comprehensive domain details. While sibling tools like 'boxes.display' and 'boxes.list' exist, the 'info' name suggests a detailed overview, but differentiation is not explicit.
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 on when to use this tool versus alternatives like boxes.display or boxes.list. No exclusions or context provided, leaving the agent to infer usage from the tool name alone.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List all libvirt domains (VMs) managed by GNOME Boxes/libvirt
| 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 should disclose behavioral traits like read-only safety. It mentions scope (managed by GNOME Boxes) but fails to state that listing is a read operation with no side effects.
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?
A single, front-loaded sentence with no extraneous words. Every part is relevant.
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?
No output schema and no description of the return format. A list tool should indicate what is returned (e.g., VM names, objects) to enable correct invocation and chaining.
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?
No parameters exist, so schema coverage is 100%. The description adds no parameter info, but none is needed. Baseline score 4 applies.
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 libvirt domains managed by GNOME Boxes). It distinguishes from siblings like boxes.display and boxes.info without overlapping.
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 explicit when-to-use or when-not-to-use guidance. The description implies usage for obtaining a list of VMs, but lacks context about prerequisites, alternatives, or conditions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Reboot a running domain
| Name | Required | Description | Default |
|---|---|---|---|
| nameOrUuid | Yes | Domain name or UUID |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description bears full responsibility for behavioral context. It only states 'running domain' implying a prerequisite, but does not disclose whether the reboot is graceful, what happens if the domain is not running, or any other behaviors.
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 very concise (one short sentence), but it omits necessary details. It is front-loaded but under-specified for a tool with no annotations.
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 tool with one parameter and no output schema, the description is insufficient. It does not explain what happens after reboot, error conditions, or any return information. More context is needed.
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?
Parameter description in schema is 'Domain name or UUID', which fully covers the parameter. The tool description adds no additional meaning beyond what the schema already provides. With 100% schema coverage, baseline is 3.
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 'Reboot a running domain' clearly states the action (reboot) and resource (domain), and distinguishes from siblings like shutdown or start by specifying 'running'. However, it lacks explicit differentiation from similar tools like boxes.shutdown.
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 like boxes.shutdown or boxes.start. The description does not mention prerequisites or context for use.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Resume a suspended domain
| Name | Required | Description | Default |
|---|---|---|---|
| nameOrUuid | Yes | Domain name or UUID |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, and the description does not disclose any behavioral traits beyond the action. It omits details about whether the operation is safe, destructive, or requires permissions.
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?
Extremely concise with no wasted words. However, it could be slightly more informative without losing conciseness.
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 (1 parameter, no output schema, no annotations), the description is incomplete. It lacks behavioral context, usage caveats, or return value expectations.
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 coverage is 100%, so the baseline is 3. The description adds no additional meaning beyond what the schema already provides for the parameter.
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 (resume) and resource (suspended domain). However, it does not distinguish from sibling tools like 'boxes.start' or 'boxes.reboot', which could have overlapping functionality.
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 on when to use this tool versus alternatives. Implicitly, it should be used when a domain is suspended, but no exclusions or context about prerequisites are provided.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Shutdown/Power off a domain (graceful by default)
| Name | Required | Description | Default |
|---|---|---|---|
| force | No | If true, force off (destroy) | |
| nameOrUuid | Yes | Domain name or UUID |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description bears full burden. It explains the default graceful shutdown and the force option for immediate destruction, but omits details such as authentication needs, rate limits, resource state transitions, or confirmation prompts. Basic behavioral traits are disclosed, but more context is expected.
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 action and default behavior. Every word is informative, with no redundancy or unnecessary details.
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 relatively simple tool with two parameters and no output schema, the description covers the main behavioral aspects (default graceful, force option). It is missing some context around post-shutdown state and differentiation from suspend/reboot, but overall adequate.
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 coverage is 100% with clear parameter descriptions. The description adds only the context of 'graceful by default' and implies the force parameter's effect, but does not introduce new meaning beyond the schema. Baseline 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 action ('Shutdown/Power off') and the resource ('a domain'), with a qualifying note about default gracefulness. This distinguishes it from sibling tools like boxes.reboot (restart) and boxes.suspend (pause), providing clear purpose.
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 powering off a domain but does not explicitly state when to prefer this over alternatives like boxes.reboot or boxes.undefine. There is no mention of when not to use, prerequisites, or preconditions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Create a snapshot for a domain
| Name | Required | Description | Default |
|---|---|---|---|
| snapshot | Yes | Snapshot name | |
| nameOrUuid | Yes | Domain name or UUID | |
| description | No | Snapshot description |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided. The description does not disclose behaviors like whether the snapshot is taken immediately, what happens if the name already exists, or any impact on the domain. This is insufficient for a creation tool.
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?
Extremely concise (one sentence) but lacks important details. It is front-loaded but sacrifices completeness for brevity.
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 3 parameters, no output schema, and no annotations, the description is inadequate. It does not explain return values, error scenarios, or behavior on duplicate names, making it incomplete for 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 coverage is 100%, so the description adds no extra meaning beyond the schema. The baseline of 3 is appropriate; the description does not elaborate on parameter formats, constraints, or relationships.
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 'Create a snapshot for a domain' uses a specific verb and resource, clearly indicating the action on a distinct object. It distinguishes itself from sibling snapshot tools like delete, list, and revert.
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 on when to create a snapshot versus other snapshot operations (delete, list, revert). No prerequisites mentioned, such as domain existence or snapshot name uniqueness.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Delete a snapshot
| Name | Required | Description | Default |
|---|---|---|---|
| snapshot | Yes | Snapshot name | |
| nameOrUuid | Yes | Domain name or UUID |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden for behavioral disclosure. It only says 'Delete a snapshot', which is a tautology of the tool name, and provides no information about side effects, permanence, or required domain state. This is insufficient 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 very concise at 5 words, but it is under-specified and lacks necessary details that would earn its place. It is not verbose, but it fails to add value beyond the tool name. A more balanced length with additional context would improve it.
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 simplicity of the tool and the lack of output schema or annotations, the description is incomplete. It does not explain the outcome, any confirmation behavior, or constraints. The description covers only the basic action, leaving gaps in understanding for the agent.
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 baseline is 3. The description does not add meaning to the parameters beyond what the schema provides, but it also does not contradict or mislead. The parameters are minimally described in the schema.
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 'Delete a snapshot' clearly states the action and resource, and distinguishes from sibling tools like 'boxes.snapshots.create' and 'boxes.snapshots.revert'. However, it could be slightly more precise by specifying the domain context.
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 usage guidelines are provided. The description does not indicate when to use this tool versus alternatives such as 'boxes.snapshots.revert' or 'boxes.snapshots.list', nor any prerequisites or conditions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List snapshots for a domain
| Name | Required | Description | Default |
|---|---|---|---|
| nameOrUuid | Yes | Domain name or UUID |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations exist, and the description provides no behavioral details beyond the minimal 'List snapshots'. No mention of order, pagination, required permissions, or side effects.
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?
Extremely concise at one sentence and five words. Could be improved with additional context without sacrificing conciseness, but currently not verbose.
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 list tool without an output schema, the description should hint at return format (e.g., snapshot IDs, names, dates). It does not. Also lacks information on whether the domain must exist.
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 a clear description for the only parameter ('Domain name or UUID'). The tool description adds no additional meaning, so 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 'List snapshots for a domain', which specifies the verb and resource. The name already differentiates from sibling tools like create/delete/revert, so no further differentiation is needed.
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 information on when to use this tool versus alternatives like boxes.snapshots.create or boxes.snapshots.revert. No prerequisites or context provided.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Revert a domain to a snapshot
| Name | Required | Description | Default |
|---|---|---|---|
| snapshot | Yes | Snapshot name | |
| nameOrUuid | Yes | Domain name or UUID |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are present, and the description does not disclose behavioral traits such as whether the operation is destructive, reversible, or requires specific permissions. The agent gets no sense of side effects.
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, concise sentence with no wasted words. However, it could be slightly more informative without being verbose.
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 tool that performs a potentially destructive action, the description lacks critical context about what happens when a snapshot is reverted. The agent cannot determine prerequisites or outcomes.
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 covers both parameters with descriptions ('Snapshot name', 'Domain name or UUID'). The tool description adds no additional meaning beyond what the schema already provides, so the score is at baseline.
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 'Revert a domain to a snapshot' clearly states the action and resource. It distinguishes from sibling tools like create, delete, list, and other domain operations. However, 'revert' could be more specific about the exact effect.
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, limitations, or when a revert is appropriate.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Start a domain (VM)
| Name | Required | Description | Default |
|---|---|---|---|
| nameOrUuid | Yes | Domain name or UUID |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations exist, so description must carry full burden. It only states 'start', lacking details on permissions, side effects (e.g., domain transitions to running), or behavior if domain is already running.
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?
Single sentence with no redundancy. Efficient but could be front-loaded with more context.
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 1 required parameter and no output schema or annotations, the description is too sparse. It lacks prerequisites, error conditions, and state transition details needed for safe invocation.
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 covers 100% of parameters with 'Domain name or UUID'. The tool description adds no extra meaning, so 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?
Description clearly states verb ('start') and resource ('domain (VM)'), which distinguishes from siblings like 'shutdown' or 'suspend'. However, it does not clarify subtle distinctions like the difference between 'start' and 'resume' for a suspended domain.
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 usage guidelines provided. Does not specify when to use this tool (e.g., domain must be stopped) nor mention alternatives like 'resume' for suspended domains.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Suspend a running domain
| Name | Required | Description | Default |
|---|---|---|---|
| nameOrUuid | Yes | Domain name or UUID |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are present, and the description does not disclose any behavioral traits such as impact on network connections, state changes, or side effects. It only states the basic action without detail.
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 concise sentence with no unnecessary words. However, it could be slightly expanded to include key behavioral context without losing conciseness.
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 insufficient. It does not explain the implications of suspension, how to reverse it, or any required domain state, leaving the agent underinformed.
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% for the single parameter 'nameOrUuid', which is adequately described as 'Domain name or UUID'. The description adds no further semantic value beyond the schema.
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 ('Suspend') and the resource ('a running domain'). It is specific and avoids tautology, but does not differentiate from sibling tools like 'shutdown' or 'stop', which could cause confusion.
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 like 'boxes.shutdown' or 'boxes.reboot'. The description does not indicate prerequisites or post-conditions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Undefine a domain (remove from libvirt). Storage is NOT deleted.
| Name | Required | Description | Default |
|---|---|---|---|
| nameOrUuid | Yes | Domain name or UUID | |
| keepStorage | No | Keep storage (default: true) |
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 discloses a key behavioral trait (storage not deleted), but omits other important details such as whether the domain must be shut down first, the irreversible nature, or permission requirements.
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 with two sentences, front-loading the action and key fact. Every sentence earns its place with no wasted words.
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 tool with 2 parameters and no output schema, the description covers the purpose and a critical behavioral note. However, it lacks context about prerequisites (e.g., domain shutdown) and reversibility, leaving some gaps for an AI agent.
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 coverage is 100%, but the description adds meaning by stating 'Storage is NOT deleted', which provides context for the keepStorage parameter. It clarifies the effect without directly mentioning the parameter name.
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 'Undefine' and the resource 'a domain', with explicit clarification that it removes from libvirt and that storage is not deleted. This differentiates it from sibling tools like boxes.shutdown or boxes.start.
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 explicit guidance on when to use this tool versus alternatives, nor any prerequisites (e.g., domain must be shut down). The description implies usage for removing a domain but lacks when-not-to-use or alternative suggestions.
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.
v0.1.0boxes.displayboxes.infoboxes.listboxes.rebootboxes.resumeboxes.shutdownboxes.snapshots.createboxes.snapshots.deleteboxes.snapshots.listboxes.snapshots.revertboxes.startboxes.suspendboxes.undefineEach tool targets a distinct action (e.g., start, shutdown, snapshot operations) with no overlap. Snapshots are namespaced under 'snapshots' to further differentiate from domain-level actions.
All tools follow a consistent 'boxes.<action>' pattern, with snapshot sub-tools using 'boxes.snapshots.<action>'. Names are lowercase with dots and use verbs for actions (list, create, delete).
13 tools is well-scoped for managing libvirt domains, covering lifecycle, snapshots, and info display. The number feels complete without being excessive.
Core VM lifecycle (start, shutdown, reboot, suspend, resume, undefine) and snapshot CRUD are covered. Missing domain modification (e.g., edit config) is a minor gap, but the set handles essential operations.
Unclaimed servers have limited discoverability.
If you are the server author, to access and configure the admin panel.
Manage Sprites: sandboxed compute environments with exec, services, and checkpoints.
Provides capabilities that let LLM agents perform a range of infrastructure management tasks.
Read GPU instances, types, images, filesystems and firewall rules; launch and terminate instances.
Snapshot and restore service for agent state and DID-bound configuration
We provide all the information about MCP servers via our MCP API.
curl -X GET 'https://glama.ai/api/mcp/v1/servers/btafoya/boxes-mcp'
If you have feedback or need assistance with the MCP directory API, please join our Discord server
