# Fleet MCP
A Model Context Protocol (MCP) server that enables AI assistants to interact with [Fleet Device Management](https://fleetdm.com) for device management, security monitoring, and compliance enforcement.
## Features
- **Host Management**: List, search, query, and manage hosts across your fleet
- **Live Query Execution**: Run osquery queries in real-time against hosts
- **Policy Management**: Create, update, and monitor compliance policies
- **Software Inventory**: Track software installations and vulnerabilities across devices
- **Team & User Management**: Organize hosts and users into teams
- **Osquery Table Discovery**: Dynamic discovery and documentation of osquery tables
- **Read-Only Mode**: Safe exploration with optional SELECT-only query execution
- **Activity Monitoring**: Track Fleet activities and audit logs
## Quick Start
Just want to dive right in? This will set up fleet-mcp with read-only access and SELECT query execution enabled. Just replace the `FLEET_SERVER_URL` and `FLEET_API_TOKEN` with your own.
```json
{
"mcpServers": {
"fleet": {
"command": "uvx",
"args": ["fleet-mcp", "run"],
"env": {
"FLEET_SERVER_URL": "https://your-fleet-instance.com",
"FLEET_API_TOKEN": "your-api-token",
"FLEET_READONLY": "true",
"FLEET_ALLOW_SELECT_QUERIES": "true"
}
}
}
}
```
See the [Available Tools](#available-tools) section below for a complete list of tools.
---
<!--
<details>
<summary><b>Local Installation</b></summary>
### From PyPI
```bash
pip install fleet-mcp
```
### From Source
```bash
git clone https://github.com/SimplyMinimal/fleet-mcp.git
cd fleet-mcp
pip install -e .
```
### Using uv (recommended for development)
```bash
git clone https://github.com/SimplyMinimal/fleet-mcp.git
cd fleet-mcp
uv sync --dev
```
</details> -->
<!-- ### 1. Initialize Configuration
```bash
fleet-mcp init-config
```
This creates a `fleet-mcp.toml` configuration file. Edit it with your Fleet server details:
```toml
[fleet]
server_url = "https://your-fleet-instance.com"
api_token = "your-api-token"
readonly = true # Safe default - enables read-only mode
allow_select_queries = false # Set to true to allow SELECT queries
```
### 2. Test Connection
```bash
fleet-mcp test
```
### 3. Run the MCP Server
```bash
fleet-mcp run
``` -->
## MCP Client Configuration
Fleet MCP can be integrated with various MCP-compatible clients. Below are configuration examples for popular clients.
### Prerequisites
Before configuring any MCP client, ensure you have:
1. **Install `uv`** (recommended) or `pip`:
```bash
# Install uv (recommended)
curl -LsSf https://astral.sh/uv/install.sh | sh
# Or use pip
pip install fleet-mcp
```
2. **Fleet API Token**: Generate an API token from your Fleet instance:
Option 1)
- Log into Fleet UI
- Navigate to: My account → Get API token
- Copy the token for use in configuration
Option 2)
- Create an API-Only user with `fleetctl`
```bash
# Generate an API-Only User and get the token
fleetctl user create --name Fleet-MCP --email <email> --password <password> --role admin --api-only
```
> **Note**: This API token and your fleet instance URL (https://your-fleet-instance.com) will be used in the client configuration.
3. **Pick Your Client**: Choose your preferred AI assistant client and follow the corresponding setup instructions below.
<details>
<summary><b>Install in Claude Desktop</b></summary>
#### Configuration File Location
- **macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`
- **Windows**: `%APPDATA%\Claude\claude_desktop_config.json`
- **Linux**: `~/.config/Claude/claude_desktop_config.json`
#### Configuration
```json
{
"mcpServers": {
"fleet": {
"command": "uvx",
"args": ["fleet-mcp", "run"],
"env": {
"FLEET_SERVER_URL": "https://your-fleet-instance.com",
"FLEET_API_TOKEN": "your-api-token",
"FLEET_READONLY": "true",
"FLEET_ALLOW_SELECT_QUERIES": "true"
}
}
}
}
```
> **Note:** Replace `uvx` with `fleet-mcp` if you've installed the package globally. For enhanced security, use `--config` flag to reference a TOML file instead of embedding tokens (see [Security Best Practices](#security-best-practices)).
</details>
<details>
<summary><b>Install in Cursor</b></summary>
Go to: `Settings` → `Cursor Settings` → `MCP` → `Add new global MCP server`
Install globally in `~/.cursor/mcp.json` or per-project in `.cursor/mcp.json`. See [Cursor MCP docs](https://docs.cursor.com/context/model-context-protocol) for more info.
```json
{
"mcpServers": {
"fleet": {
"command": "uvx",
"args": ["fleet-mcp", "run"],
"env": {
"FLEET_SERVER_URL": "https://your-fleet-instance.com",
"FLEET_API_TOKEN": "your-api-token",
"FLEET_READONLY": "true",
"FLEET_ALLOW_SELECT_QUERIES": "true"
}
}
}
}
```
</details>
<details>
<summary><b>Install in Cline (VS Code Extension)</b></summary>
**Config Location:** `~/.cline/mcp_settings.json` (macOS/Linux) or `%USERPROFILE%\.cline\mcp_settings.json` (Windows)
Alternatively: VS Code Settings → Search "Cline: MCP Settings" → Edit JSON
```json
{
"mcpServers": {
"fleet": {
"command": "uvx",
"args": ["fleet-mcp", "run"],
"env": {
"FLEET_SERVER_URL": "https://your-fleet-instance.com",
"FLEET_API_TOKEN": "your-api-token",
"FLEET_READONLY": "true",
"FLEET_ALLOW_SELECT_QUERIES": "true"
}
}
}
}
```
</details>
<details>
<summary><b>Install in Continue (VS Code Extension)</b></summary>
**Config Location:** `~/.continue/config.json`
```json
{
"mcpServers": [
{
"name": "fleet",
"command": "uvx",
"args": ["fleet-mcp", "run"],
"env": {
"FLEET_SERVER_URL": "https://your-fleet-instance.com",
"FLEET_API_TOKEN": "your-api-token",
"FLEET_READONLY": "true",
"FLEET_ALLOW_SELECT_QUERIES": "true"
}
}
]
}
```
</details>
<details>
<summary><b>Install in Zed Editor</b></summary>
**Config Location:** `~/.config/zed/settings.json` (macOS/Linux) or `%APPDATA%\Zed\settings.json` (Windows)
```json
{
"context_servers": {
"fleet": {
"command": {
"path": "uvx",
"args": ["fleet-mcp", "run"]
},
"settings": {
"env": {
"FLEET_SERVER_URL": "https://your-fleet-instance.com",
"FLEET_API_TOKEN": "your-api-token",
"FLEET_READONLY": "true",
"FLEET_ALLOW_SELECT_QUERIES": "true"
}
}
}
}
}
```
</details>
<details>
<summary><b>Install in Windsurf</b></summary>
See [Windsurf MCP docs](https://docs.windsurf.com/windsurf/cascade/mcp) for more info.
```json
{
"mcpServers": {
"fleet": {
"command": "uvx",
"args": ["fleet-mcp", "run"],
"env": {
"FLEET_SERVER_URL": "https://your-fleet-instance.com",
"FLEET_API_TOKEN": "your-api-token",
"FLEET_READONLY": "true",
"FLEET_ALLOW_SELECT_QUERIES": "true"
}
}
}
}
```
</details>
<details>
<summary><b>Install in VS Code</b></summary>
See [VS Code MCP docs](https://code.visualstudio.com/docs/copilot/chat/mcp-servers) for more info.
```json
"mcp": {
"servers": {
"fleet": {
"type": "stdio",
"command": "uvx",
"args": ["fleet-mcp", "run"],
"env": {
"FLEET_SERVER_URL": "https://your-fleet-instance.com",
"FLEET_API_TOKEN": "your-api-token",
"FLEET_READONLY": "true",
"FLEET_ALLOW_SELECT_QUERIES": "true"
}
}
}
}
```
</details>
<details>
<summary><b>Install in Sourcegraph Cody</b></summary>
**Config Location:** `~/Library/Application Support/Cody/mcp_settings.json` (macOS), `%APPDATA%\Cody\mcp_settings.json` (Windows), or `~/.config/Cody/mcp_settings.json` (Linux)
```json
{
"mcpServers": {
"fleet": {
"command": "uvx",
"args": ["fleet-mcp", "run"],
"env": {
"FLEET_SERVER_URL": "https://your-fleet-instance.com",
"FLEET_API_TOKEN": "your-api-token",
"FLEET_READONLY": "true",
"FLEET_ALLOW_SELECT_QUERIES": "true"
}
}
}
}
```
</details>
<details>
<summary><b>Install in Augment Code</b></summary>
**Via UI:** Hamburger menu → Settings → Tools → + Add MCP → Enter `uvx fleet-mcp run` → Name: "Fleet" → Add
**Manual Config:** Settings → Advanced → Edit settings.json
```json
"augment.advanced": {
"mcpServers": [
{
"name": "fleet",
"command": "uvx",
"args": ["fleet-mcp", "run"],
"env": {
"FLEET_SERVER_URL": "https://your-fleet-instance.com",
"FLEET_API_TOKEN": "your-api-token",
"FLEET_READONLY": "true",
"FLEET_ALLOW_SELECT_QUERIES": "true"
}
}
]
}
```
</details>
<details>
<summary><b>Install in LM Studio</b></summary>
Navigate to `Program` → `Install` → `Edit mcp.json`. See [LM Studio MCP Support](https://lmstudio.ai/blog/lmstudio-v0.3.17).
```json
{
"mcpServers": {
"fleet": {
"command": "uvx",
"args": ["fleet-mcp", "run"],
"env": {
"FLEET_SERVER_URL": "https://your-fleet-instance.com",
"FLEET_API_TOKEN": "your-api-token",
"FLEET_READONLY": "true",
"FLEET_ALLOW_SELECT_QUERIES": "true"
}
}
}
}
```
</details>
<details>
<summary><b>Generic MCP Client Configuration</b></summary>
For other MCP-compatible clients, use this general pattern:
```json
{
"mcpServers": {
"fleet": {
"command": "uvx",
"args": ["fleet-mcp", "run"],
"env": {
"FLEET_SERVER_URL": "https://your-fleet-instance.com",
"FLEET_API_TOKEN": "your-api-token",
"FLEET_READONLY": "true",
"FLEET_ALLOW_SELECT_QUERIES": "true"
}
}
}
}
```
</details>
### Configuration Options Reference
| Environment Variable | Description | Default | Required |
|---------------------|-------------|---------|----------|
| `FLEET_SERVER_URL` | Fleet server URL | - | ✅ |
| `FLEET_API_TOKEN` | Fleet API token | - | ✅ |
| `FLEET_READONLY` | Enable read-only mode | `true` | ❌ |
| `FLEET_ALLOW_SELECT_QUERIES` | Allow SELECT queries in read-only mode | `false` | ❌ |
| `FLEET_VERIFY_SSL` | Verify SSL certificates | `true` | ❌ |
| `FLEET_TIMEOUT` | Request timeout (seconds) | `30` | ❌ |
| `FLEET_MAX_RETRIES` | Maximum request retries | `3` | ❌ |
> **Note:** All clients above use the same environment variables. Replace `uvx` with `fleet-mcp` if installed globally.
### Security Best Practices
1. **Use Config Files**: Store tokens in TOML files: `"args": ["fleet-mcp", "--config", "~/.config/fleet-mcp.toml", "run"]`
2. **File Permissions**: `chmod 600 ~/.config/fleet-mcp.toml`
3. **Read-Only Mode**: Start with `FLEET_READONLY=true` (default)
4. **Token Rotation**: Regularly rotate Fleet API tokens
5. **Environment-Specific Configs**: Use separate configs for dev/prod
## Available Tools
Fleet MCP provides tools organized into two main groups based on operational mode. Click to expand each group.
<details>
<summary><b>Read-Only Tools (Always Available)</b></summary>
These tools are available in all modes (`readonly=true` or `readonly=false`). They only read data and never modify Fleet state.
#### Host Management
- `fleet_list_hosts` - List hosts with filtering, pagination, and search
- `fleet_get_host` - Get detailed information about a specific host by ID
- `fleet_get_host_by_identifier` - Get host by hostname, UUID, or hardware serial
- `fleet_search_hosts` - Search hosts by hostname, UUID, serial number, or IP
- `fleet_list_host_upcoming_activities` - List upcoming activities for a specific host
- `fleet_list_host_past_activities` - List past activities for a specific host
- `fleet_get_host_mdm` - Get MDM information for a specific host
- `fleet_list_host_certificates` - List certificates for a specific host
- `fleet_get_host_macadmins` - Get macadmins data (Munki, MDM profiles) for a host
- `fleet_get_host_device_mapping` - Get device mapping information for a host
- `fleet_get_host_encryption_key` - Get disk encryption recovery key for a host
#### Query Management
- `fleet_list_queries` - List all saved queries with pagination
- `fleet_get_query` - Get details of a specific saved query
- `fleet_get_query_report` - Get the latest results from a scheduled query
#### Policy Management
- `fleet_list_policies` - List all compliance policies
- `fleet_get_policy_results` - Get compliance results for a specific policy
#### Software & Vulnerabilities
- `fleet_list_software` - List software inventory across the fleet
- `fleet_get_software` - Get detailed information about a specific software item
- `fleet_get_host_software` - Get software installed on a specific host
- `fleet_get_vulnerabilities` - List known vulnerabilities with filtering
- `fleet_get_cve` - Get detailed information about a specific CVE
- `fleet_search_software` - Search for software by name
- `fleet_find_software_on_host` - Find specific software on a host by hostname
- `fleet_get_software_install_result` - Get the result of a software installation request
- `fleet_list_software_titles` - List software titles across the fleet
- `fleet_get_software_title` - Get detailed information about a specific software title
#### Team Management
- `fleet_list_teams` - List all teams
- `fleet_get_team` - Get details of a specific team
- `fleet_list_team_users` - List all users that are members of a specific team
- `fleet_get_team_secrets` - List team-specific enroll secrets
#### User Management
- `fleet_list_users` - List all users with filtering
- `fleet_get_user` - Get details of a specific user
- `fleet_list_user_sessions` - List active sessions for a user
- `fleet_get_session` - Get session details by ID
#### Label Management
- `fleet_list_labels` - List all labels
- `fleet_get_label` - Get detailed information about a specific label
#### Pack Management
- `fleet_list_packs` - List all query packs
- `fleet_get_pack` - Get detailed information about a specific pack
- `fleet_list_scheduled_queries` - List scheduled queries in a specific pack
#### Script Management
- `fleet_list_scripts` - List all scripts available in Fleet
- `fleet_get_script` - Get details of a specific script
- `fleet_get_script_result` - Get the result of a script execution
- `fleet_list_batch_scripts` - List batch script executions
- `fleet_get_batch_script` - Get details of a batch script execution
- `fleet_list_batch_script_hosts` - List hosts in a batch script execution
- `fleet_list_host_scripts` - List scripts available for a specific host
#### MDM Management
- `fleet_list_mdm_commands` - List MDM commands that have been executed
- `fleet_get_mdm_command_results` - Get results of MDM commands
- `fleet_list_mdm_profiles` - List MDM configuration profiles
- `fleet_get_host_mdm_profiles` - Get MDM profiles installed on a specific host
- `fleet_get_mdm_profiles_summary` - Get summary of MDM profile deployment status
- `fleet_get_filevault_summary` - Get FileVault encryption summary
- `fleet_list_mdm_devices` - List all MDM-enrolled Apple devices
- `fleet_get_bootstrap_metadata` - Get metadata about a bootstrap package for a team
- `fleet_get_bootstrap_summary` - Get aggregated summary about bootstrap package deployment
- `fleet_get_setup_assistant` - Get the MDM Apple Setup Assistant configuration
- `fleet_list_mdm_apple_installers` - List all Apple MDM installers
#### VPP/App Store Management
- `fleet_list_app_store_apps` - List App Store apps available for installation
- `fleet_list_vpp_tokens` - List VPP tokens configured in Fleet
#### Configuration Management
- `fleet_get_config` - Get the current Fleet application configuration
- `fleet_get_enroll_secrets` - Get the enrollment secrets configuration
- `fleet_get_certificate` - Get the Fleet server certificate chain
- `fleet_get_version` - Get the Fleet server version information
#### Secret Management
- `fleet_list_secrets` - List secret variables in Fleet
#### Invite Management
- `fleet_list_invites` - List pending user invites
- `fleet_verify_invite` - Verify an invite token and get invite details
#### Carve Management
- `fleet_list_carves` - List file carve sessions
- `fleet_get_carve` - Get detailed information about a specific carve session
- `fleet_get_carve_block` - Get a specific block of data from a carve session
#### Device Management
- `fleet_get_device_info` - Get device information using a device token
#### Activity Monitoring
- `fleet_list_activities` - List Fleet activities and audit logs
#### Osquery Table Discovery & Reference
- `fleet_list_osquery_tables` - List available osquery tables with dynamic discovery
- `fleet_get_osquery_table_schema` - Get detailed schema for a specific table
- `fleet_suggest_tables_for_query` - Get AI-powered table suggestions based on intent
#### System
- `fleet_health_check` - Check Fleet server connectivity and authentication
</details>
<details>
<summary><b>Write/Modify Tools (Requires <code>readonly=false</code>)</b></summary>
These tools can modify Fleet state and are only available when `readonly=false` is set in the configuration. This will allow you to make changes to your Fleet environment such as creating scripts, policies, managing teams, etc. in addition to the read-only tools. Setting to `readonly=true` (default) will disable these tools.
#### Host Management
- `fleet_delete_host` - Remove a host from Fleet
- `fleet_transfer_hosts` - Transfer hosts to a different team
- `fleet_query_host` - Run an ad-hoc live query against a specific host
- `fleet_query_host_by_identifier` - Run a live query by hostname/UUID/serial
- `fleet_cancel_host_activity` - Cancel an upcoming activity for a specific host
- `fleet_lock_host` - Lock a host device remotely
- `fleet_unlock_host` - Unlock a host device remotely
- `fleet_unenroll_host_mdm` - Unenroll a host from MDM
- `fleet_add_labels_to_host` - Add labels to a host
- `fleet_remove_labels_from_host` - Remove labels from a host
- `fleet_refetch_host` - Force a host to refetch and update its data immediately
#### Query Management
- `fleet_create_query` - Create a new saved query
- `fleet_delete_query` - Delete a saved query
- `fleet_run_live_query` - Execute a live query against specified hosts
- `fleet_run_saved_query` - Run a saved query against hosts
#### Policy Management
- `fleet_create_policy` - Create a new compliance policy
- `fleet_update_policy` - Update an existing policy
- `fleet_delete_policy` - Delete a policy
#### Software Management
- `fleet_install_software` - Install software on a specific host
- `fleet_batch_set_software` - Batch upload/set software installers for a team
#### Team Management
- `fleet_create_team` - Create a new team
- `fleet_add_team_users` - Add one or more users to a specific team
- `fleet_remove_team_user` - Remove a specific user from a team
#### User Management
- `fleet_create_user` - Create a new user
- `fleet_update_user` - Update an existing user
- `fleet_delete_session` - Delete/invalidate a specific session
- `fleet_delete_user_sessions` - Delete all sessions for a specific user
#### Label Management
- `fleet_create_label` - Create a new label
- `fleet_update_label` - Update an existing label
- `fleet_delete_label` - Delete a label by name
#### Pack Management
- `fleet_create_pack` - Create a new query pack
- `fleet_update_pack` - Update an existing pack
- `fleet_delete_pack` - Delete a pack by name
#### Script Management
- `fleet_run_script` - Run a script on a specific host
- `fleet_run_batch_script` - Run a script on multiple hosts
- `fleet_cancel_batch_script` - Cancel a batch script execution
- `fleet_create_script` - Create and upload a new script
- `fleet_modify_script` - Modify an existing script
- `fleet_delete_script` - Delete a script
#### MDM Management
- `fleet_upload_mdm_profile` - Upload a new MDM configuration profile
- `fleet_delete_mdm_profile` - Delete an MDM configuration profile
- `fleet_lock_device` - Lock an MDM-enrolled device remotely
- `fleet_upload_bootstrap_package` - Upload a bootstrap package for MDM enrollment
- `fleet_delete_bootstrap_package` - Delete a bootstrap package for a team
- `fleet_create_setup_assistant` - Create or update an MDM Apple Setup Assistant
- `fleet_delete_setup_assistant` - Delete the MDM Apple Setup Assistant
- `fleet_upload_mdm_apple_installer` - Upload a new Apple MDM installer package
**Note: The wipe device tool is currently disabled as it is too dangerous. It may be revisited later if really needed.**
#### VPP/App Store Management
- `fleet_add_app_store_app` - Add an App Store app for distribution
- `fleet_update_app_store_app` - Update App Store app settings
- `fleet_delete_vpp_token` - Delete a VPP token
#### Configuration Management
- `fleet_update_config` - Update the Fleet application configuration
- `fleet_update_enroll_secrets` - Update the enrollment secrets configuration
#### Secret Management
- `fleet_create_secret` - Create a new secret variable
- `fleet_delete_secret` - Delete a secret variable by ID
#### Invite Management
- `fleet_create_invite` - Create a new user invite
- `fleet_update_invite` - Update a pending invite
- `fleet_delete_invite` - Delete a pending invite
</details>
## Configuration
Fleet MCP supports three configuration methods (in order of precedence):
1. **Command-line arguments** (highest priority)
2. **Environment variables** (with `FLEET_` prefix)
3. **Configuration file** (recommended for security)
### Configuration File (Recommended)
Create `fleet-mcp.toml`:
```toml
[fleet]
server_url = "https://your-fleet-instance.com" # Required
api_token = "your-api-token" # Required
verify_ssl = true # Default: true
timeout = 30 # Default: 30 seconds
max_retries = 3 # Default: 3
readonly = true # Default: true
allow_select_queries = false # Default: false
```
### Environment Variables
See [Configuration Options Reference](#configuration-options-reference) for all available variables. Environment variables use the `FLEET_` prefix and override config file settings.
### Command-Line Arguments
```bash
fleet-mcp --server-url https://fleet.example.com --api-token YOUR_TOKEN run
```
Options: `--config`, `--server-url`, `--api-token`, `--readonly`, `--verbose`
## Read-Only Mode
Fleet MCP runs in **read-only mode by default** for safe exploration without risk of changes.
### Three Operational Modes
| Mode | Config | Capabilities | Best For |
|------|--------|--------------|----------|
| **Strict Read-Only** (Default) | `readonly=true`<br>`allow_select_queries=false` | ✅ View all resources<br>❌ No query execution<br>❌ No modifications | Safe exploration |
| **Read-Only + SELECT** | `readonly=true`<br>`allow_select_queries=true` | ✅ View all resources<br>✅ Run SELECT queries<br>❌ No modifications | Active monitoring |
| **Full Write** | `readonly=false` | ✅ All operations<br>⚠️ AI can modify Fleet | Full management |
### Configuration Examples
```toml
# Strict Read-Only (Default)
[fleet]
readonly = true
allow_select_queries = false
```
```toml
# Read-Only with SELECT Queries
[fleet]
readonly = true
allow_select_queries = true
```
```toml
# Full Write Access (⚠️ Use with caution) - Recommended to have LLM prompt for confirmation before making changes
[fleet]
readonly = false
```
## CLI Commands
| Command | Description | Example |
|---------|-------------|---------|
| `run` | Start MCP server | `fleet-mcp run` |
| `test` | Test Fleet connection | `fleet-mcp test` |
| `init-config` | Create config template | `fleet-mcp init-config` |
| `version` | Show version | `fleet-mcp version` |
**Global Options:** `--config`, `--verbose`, `--server-url`, `--api-token`, `--readonly`
## Usage Examples
### Example 1: List All Teams
```python
# In Claude Desktop or any MCP client
"List all teams in Fleet"
```
### Example 2: Find Software on a Host
```python
"What version of Chrome is installed on host-123?"
```
### Example 3: Run a Query
```python
# With allow_select_queries=true
"Run a query to find all processes listening on port 80"
```
### Example 4: Check Compliance
```python
"Show me which hosts are failing the disk encryption policy"
```
### Example 5: Discover Osquery Tables
```python
"What osquery tables are available for monitoring network connections?"
```
## Development
<details>
<summary><b>Development Setup</b></summary>
This project uses [uv](https://docs.astral.sh/uv/) for dependency management.
### Setup
```bash
git clone https://github.com/SimplyMinimal/fleet-mcp.git
cd fleet-mcp
uv sync --dev
```
### Common Tasks
| Task | Command |
|------|---------|
| Run tests | `uv run pytest` |
| Format code | `uv run black src tests && uv run isort src tests` |
| Type check | `uv run mypy src` |
| Lint | `uv run ruff check src tests` |
| Add dependency | `uv add package-name` |
| Add dev dependency | `uv add --group dev package-name` |
### Project Structure
```
src/fleet_mcp/
├── cli.py # Command-line interface
├── client.py # Fleet API client
├── config.py # Configuration management
├── server.py # MCP server implementation
├── tools/ # MCP tool implementations
└── utils/ # Utilities (SQL validator, etc.)
```
</details>
## Troubleshooting
<details>
<summary><b>Server Not Appearing in Client</b></summary>
1. Validate JSON syntax in config file
2. Restart the MCP client
3. Check client logs for errors
4. Verify `uvx` or `fleet-mcp` is in PATH: `which uvx`
</details>
<details>
<summary><b>Connection Errors</b></summary>
1. Test manually: `uvx fleet-mcp test`
2. Verify `FLEET_SERVER_URL` is accessible
3. Check `FLEET_API_TOKEN` is valid
4. For self-signed certs: `FLEET_VERIFY_SSL=false`
</details>
<details>
<summary><b>Authentication Failed (401)</b></summary>
1. Verify API token is correct
2. Check token hasn't expired
3. Ensure token has appropriate permissions
4. Generate new token: Fleet UI → My account → Get API token
</details>
<details>
<summary><b>Query Validation Failed</b></summary>
1. Set `FLEET_ALLOW_SELECT_QUERIES=true`
2. Ensure query is SELECT-only (no INSERT, UPDATE, DELETE, etc.)
3. Verify osquery SQL syntax is valid
</details>
<details>
<summary><b>Tool Not Available</b></summary>
- Write operations require `FLEET_READONLY=false`
- Query execution requires `FLEET_ALLOW_SELECT_QUERIES=true`
- Check tool availability in current mode
</details>
## License
Fleet MCP is open source software licensed under the [MIT License](LICENSE).
You are free to use, modify, and distribute this software for any purpose, including commercial use, subject to the terms of the MIT License.
## Disclaimer
This project is not affiliated with or endorsed by Fleet DM. It is an independent implementation of the Model Context Protocol for interacting with [Fleet](https://fleetdm.com) instances.
Raw data
{
"_id": null,
"home_page": null,
"name": "fleet-mcp",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.10",
"maintainer_email": null,
"keywords": "device-management, fleet, mcp, osquery, security",
"author": "SimplyMinimal",
"author_email": null,
"download_url": "https://files.pythonhosted.org/packages/bf/24/dbb8a48f5032fdf4fe9377e5fb89e3c4bb353be5c1f8dd692fccf770b791/fleet_mcp-1.0.2.tar.gz",
"platform": null,
"description": "# Fleet MCP\n\nA Model Context Protocol (MCP) server that enables AI assistants to interact with [Fleet Device Management](https://fleetdm.com) for device management, security monitoring, and compliance enforcement.\n\n## Features\n\n- **Host Management**: List, search, query, and manage hosts across your fleet\n- **Live Query Execution**: Run osquery queries in real-time against hosts\n- **Policy Management**: Create, update, and monitor compliance policies\n- **Software Inventory**: Track software installations and vulnerabilities across devices\n- **Team & User Management**: Organize hosts and users into teams\n- **Osquery Table Discovery**: Dynamic discovery and documentation of osquery tables\n- **Read-Only Mode**: Safe exploration with optional SELECT-only query execution\n- **Activity Monitoring**: Track Fleet activities and audit logs\n\n\n## Quick Start\nJust want to dive right in? This will set up fleet-mcp with read-only access and SELECT query execution enabled. Just replace the `FLEET_SERVER_URL` and `FLEET_API_TOKEN` with your own.\n```json\n{\n \"mcpServers\": {\n \"fleet\": {\n \"command\": \"uvx\",\n \"args\": [\"fleet-mcp\", \"run\"],\n \"env\": {\n \"FLEET_SERVER_URL\": \"https://your-fleet-instance.com\",\n \"FLEET_API_TOKEN\": \"your-api-token\",\n \"FLEET_READONLY\": \"true\",\n \"FLEET_ALLOW_SELECT_QUERIES\": \"true\"\n }\n }\n }\n}\n```\n\nSee the [Available Tools](#available-tools) section below for a complete list of tools.\n\n---\n<!-- \n<details>\n<summary><b>Local Installation</b></summary>\n\n### From PyPI\n```bash\npip install fleet-mcp\n```\n\n### From Source\n```bash\ngit clone https://github.com/SimplyMinimal/fleet-mcp.git\ncd fleet-mcp\npip install -e .\n```\n\n### Using uv (recommended for development)\n```bash\ngit clone https://github.com/SimplyMinimal/fleet-mcp.git\ncd fleet-mcp\nuv sync --dev\n```\n</details> -->\n\n<!-- ### 1. Initialize Configuration\n```bash\nfleet-mcp init-config\n```\n\nThis creates a `fleet-mcp.toml` configuration file. Edit it with your Fleet server details:\n\n```toml\n[fleet]\nserver_url = \"https://your-fleet-instance.com\"\napi_token = \"your-api-token\"\nreadonly = true # Safe default - enables read-only mode\nallow_select_queries = false # Set to true to allow SELECT queries\n```\n\n### 2. Test Connection\n```bash\nfleet-mcp test\n```\n\n### 3. Run the MCP Server\n```bash\nfleet-mcp run\n``` -->\n\n## MCP Client Configuration\n\nFleet MCP can be integrated with various MCP-compatible clients. Below are configuration examples for popular clients.\n\n### Prerequisites\n\nBefore configuring any MCP client, ensure you have:\n\n1. **Install `uv`** (recommended) or `pip`:\n ```bash\n # Install uv (recommended)\n curl -LsSf https://astral.sh/uv/install.sh | sh\n\n # Or use pip\n pip install fleet-mcp\n ```\n\n2. **Fleet API Token**: Generate an API token from your Fleet instance: \n Option 1) \n - Log into Fleet UI\n - Navigate to: My account \u2192 Get API token\n - Copy the token for use in configuration\n\n Option 2)\n - Create an API-Only user with `fleetctl`\n ```bash\n # Generate an API-Only User and get the token\n fleetctl user create --name Fleet-MCP --email <email> --password <password> --role admin --api-only\n ```\n\n > **Note**: This API token and your fleet instance URL (https://your-fleet-instance.com) will be used in the client configuration.\n\n3. **Pick Your Client**: Choose your preferred AI assistant client and follow the corresponding setup instructions below.\n\n<details>\n<summary><b>Install in Claude Desktop</b></summary>\n\n#### Configuration File Location\n\n- **macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`\n- **Windows**: `%APPDATA%\\Claude\\claude_desktop_config.json`\n- **Linux**: `~/.config/Claude/claude_desktop_config.json`\n\n#### Configuration\n\n```json\n{\n \"mcpServers\": {\n \"fleet\": {\n \"command\": \"uvx\",\n \"args\": [\"fleet-mcp\", \"run\"],\n \"env\": {\n \"FLEET_SERVER_URL\": \"https://your-fleet-instance.com\",\n \"FLEET_API_TOKEN\": \"your-api-token\",\n \"FLEET_READONLY\": \"true\",\n \"FLEET_ALLOW_SELECT_QUERIES\": \"true\"\n }\n }\n }\n}\n```\n\n> **Note:** Replace `uvx` with `fleet-mcp` if you've installed the package globally. For enhanced security, use `--config` flag to reference a TOML file instead of embedding tokens (see [Security Best Practices](#security-best-practices)).\n\n</details>\n\n<details>\n<summary><b>Install in Cursor</b></summary>\n\nGo to: `Settings` \u2192 `Cursor Settings` \u2192 `MCP` \u2192 `Add new global MCP server`\n\nInstall globally in `~/.cursor/mcp.json` or per-project in `.cursor/mcp.json`. See [Cursor MCP docs](https://docs.cursor.com/context/model-context-protocol) for more info.\n\n```json\n{\n \"mcpServers\": {\n \"fleet\": {\n \"command\": \"uvx\",\n \"args\": [\"fleet-mcp\", \"run\"],\n \"env\": {\n \"FLEET_SERVER_URL\": \"https://your-fleet-instance.com\",\n \"FLEET_API_TOKEN\": \"your-api-token\",\n \"FLEET_READONLY\": \"true\",\n \"FLEET_ALLOW_SELECT_QUERIES\": \"true\"\n }\n }\n }\n}\n```\n\n</details>\n\n<details>\n<summary><b>Install in Cline (VS Code Extension)</b></summary>\n\n**Config Location:** `~/.cline/mcp_settings.json` (macOS/Linux) or `%USERPROFILE%\\.cline\\mcp_settings.json` (Windows)\n\nAlternatively: VS Code Settings \u2192 Search \"Cline: MCP Settings\" \u2192 Edit JSON\n\n```json\n{\n \"mcpServers\": {\n \"fleet\": {\n \"command\": \"uvx\",\n \"args\": [\"fleet-mcp\", \"run\"],\n \"env\": {\n \"FLEET_SERVER_URL\": \"https://your-fleet-instance.com\",\n \"FLEET_API_TOKEN\": \"your-api-token\",\n \"FLEET_READONLY\": \"true\",\n \"FLEET_ALLOW_SELECT_QUERIES\": \"true\"\n }\n }\n }\n}\n```\n\n</details>\n\n<details>\n<summary><b>Install in Continue (VS Code Extension)</b></summary>\n\n**Config Location:** `~/.continue/config.json`\n\n```json\n{\n \"mcpServers\": [\n {\n \"name\": \"fleet\",\n \"command\": \"uvx\",\n \"args\": [\"fleet-mcp\", \"run\"],\n \"env\": {\n \"FLEET_SERVER_URL\": \"https://your-fleet-instance.com\",\n \"FLEET_API_TOKEN\": \"your-api-token\",\n \"FLEET_READONLY\": \"true\",\n \"FLEET_ALLOW_SELECT_QUERIES\": \"true\"\n }\n }\n ]\n}\n```\n\n</details>\n\n<details>\n<summary><b>Install in Zed Editor</b></summary>\n\n**Config Location:** `~/.config/zed/settings.json` (macOS/Linux) or `%APPDATA%\\Zed\\settings.json` (Windows)\n\n```json\n{\n \"context_servers\": {\n \"fleet\": {\n \"command\": {\n \"path\": \"uvx\",\n \"args\": [\"fleet-mcp\", \"run\"]\n },\n \"settings\": {\n \"env\": {\n \"FLEET_SERVER_URL\": \"https://your-fleet-instance.com\",\n \"FLEET_API_TOKEN\": \"your-api-token\",\n \"FLEET_READONLY\": \"true\",\n \"FLEET_ALLOW_SELECT_QUERIES\": \"true\"\n }\n }\n }\n }\n}\n```\n\n</details>\n\n<details>\n<summary><b>Install in Windsurf</b></summary>\n\nSee [Windsurf MCP docs](https://docs.windsurf.com/windsurf/cascade/mcp) for more info.\n\n```json\n{\n \"mcpServers\": {\n \"fleet\": {\n \"command\": \"uvx\",\n \"args\": [\"fleet-mcp\", \"run\"],\n \"env\": {\n \"FLEET_SERVER_URL\": \"https://your-fleet-instance.com\",\n \"FLEET_API_TOKEN\": \"your-api-token\",\n \"FLEET_READONLY\": \"true\",\n \"FLEET_ALLOW_SELECT_QUERIES\": \"true\"\n }\n }\n }\n}\n```\n\n</details>\n\n<details>\n<summary><b>Install in VS Code</b></summary>\n\nSee [VS Code MCP docs](https://code.visualstudio.com/docs/copilot/chat/mcp-servers) for more info.\n\n```json\n\"mcp\": {\n \"servers\": {\n \"fleet\": {\n \"type\": \"stdio\",\n \"command\": \"uvx\",\n \"args\": [\"fleet-mcp\", \"run\"],\n \"env\": {\n \"FLEET_SERVER_URL\": \"https://your-fleet-instance.com\",\n \"FLEET_API_TOKEN\": \"your-api-token\",\n \"FLEET_READONLY\": \"true\",\n \"FLEET_ALLOW_SELECT_QUERIES\": \"true\"\n }\n }\n }\n}\n```\n\n</details>\n\n<details>\n<summary><b>Install in Sourcegraph Cody</b></summary>\n\n**Config Location:** `~/Library/Application Support/Cody/mcp_settings.json` (macOS), `%APPDATA%\\Cody\\mcp_settings.json` (Windows), or `~/.config/Cody/mcp_settings.json` (Linux)\n\n```json\n{\n \"mcpServers\": {\n \"fleet\": {\n \"command\": \"uvx\",\n \"args\": [\"fleet-mcp\", \"run\"],\n \"env\": {\n \"FLEET_SERVER_URL\": \"https://your-fleet-instance.com\",\n \"FLEET_API_TOKEN\": \"your-api-token\",\n \"FLEET_READONLY\": \"true\",\n \"FLEET_ALLOW_SELECT_QUERIES\": \"true\"\n }\n }\n }\n}\n```\n\n</details>\n\n<details>\n<summary><b>Install in Augment Code</b></summary>\n\n**Via UI:** Hamburger menu \u2192 Settings \u2192 Tools \u2192 + Add MCP \u2192 Enter `uvx fleet-mcp run` \u2192 Name: \"Fleet\" \u2192 Add\n\n**Manual Config:** Settings \u2192 Advanced \u2192 Edit settings.json\n\n```json\n\"augment.advanced\": {\n \"mcpServers\": [\n {\n \"name\": \"fleet\",\n \"command\": \"uvx\",\n \"args\": [\"fleet-mcp\", \"run\"],\n \"env\": {\n \"FLEET_SERVER_URL\": \"https://your-fleet-instance.com\",\n \"FLEET_API_TOKEN\": \"your-api-token\",\n \"FLEET_READONLY\": \"true\",\n \"FLEET_ALLOW_SELECT_QUERIES\": \"true\"\n }\n }\n ]\n}\n```\n\n</details>\n\n<details>\n<summary><b>Install in LM Studio</b></summary>\n\nNavigate to `Program` \u2192 `Install` \u2192 `Edit mcp.json`. See [LM Studio MCP Support](https://lmstudio.ai/blog/lmstudio-v0.3.17).\n\n```json\n{\n \"mcpServers\": {\n \"fleet\": {\n \"command\": \"uvx\",\n \"args\": [\"fleet-mcp\", \"run\"],\n \"env\": {\n \"FLEET_SERVER_URL\": \"https://your-fleet-instance.com\",\n \"FLEET_API_TOKEN\": \"your-api-token\",\n \"FLEET_READONLY\": \"true\",\n \"FLEET_ALLOW_SELECT_QUERIES\": \"true\"\n }\n }\n }\n}\n```\n\n</details>\n\n<details>\n<summary><b>Generic MCP Client Configuration</b></summary>\n\nFor other MCP-compatible clients, use this general pattern:\n\n```json\n{\n \"mcpServers\": {\n \"fleet\": {\n \"command\": \"uvx\",\n \"args\": [\"fleet-mcp\", \"run\"],\n \"env\": {\n \"FLEET_SERVER_URL\": \"https://your-fleet-instance.com\",\n \"FLEET_API_TOKEN\": \"your-api-token\",\n \"FLEET_READONLY\": \"true\",\n \"FLEET_ALLOW_SELECT_QUERIES\": \"true\"\n }\n }\n }\n}\n```\n\n</details>\n\n### Configuration Options Reference\n\n| Environment Variable | Description | Default | Required |\n|---------------------|-------------|---------|----------|\n| `FLEET_SERVER_URL` | Fleet server URL | - | \u2705 |\n| `FLEET_API_TOKEN` | Fleet API token | - | \u2705 |\n| `FLEET_READONLY` | Enable read-only mode | `true` | \u274c |\n| `FLEET_ALLOW_SELECT_QUERIES` | Allow SELECT queries in read-only mode | `false` | \u274c |\n| `FLEET_VERIFY_SSL` | Verify SSL certificates | `true` | \u274c |\n| `FLEET_TIMEOUT` | Request timeout (seconds) | `30` | \u274c |\n| `FLEET_MAX_RETRIES` | Maximum request retries | `3` | \u274c |\n\n> **Note:** All clients above use the same environment variables. Replace `uvx` with `fleet-mcp` if installed globally.\n\n### Security Best Practices\n\n1. **Use Config Files**: Store tokens in TOML files: `\"args\": [\"fleet-mcp\", \"--config\", \"~/.config/fleet-mcp.toml\", \"run\"]`\n2. **File Permissions**: `chmod 600 ~/.config/fleet-mcp.toml`\n3. **Read-Only Mode**: Start with `FLEET_READONLY=true` (default)\n4. **Token Rotation**: Regularly rotate Fleet API tokens\n5. **Environment-Specific Configs**: Use separate configs for dev/prod\n\n## Available Tools\n\nFleet MCP provides tools organized into two main groups based on operational mode. Click to expand each group.\n\n<details>\n<summary><b>Read-Only Tools (Always Available)</b></summary>\n\nThese tools are available in all modes (`readonly=true` or `readonly=false`). They only read data and never modify Fleet state.\n\n#### Host Management\n- `fleet_list_hosts` - List hosts with filtering, pagination, and search\n- `fleet_get_host` - Get detailed information about a specific host by ID\n- `fleet_get_host_by_identifier` - Get host by hostname, UUID, or hardware serial\n- `fleet_search_hosts` - Search hosts by hostname, UUID, serial number, or IP\n- `fleet_list_host_upcoming_activities` - List upcoming activities for a specific host\n- `fleet_list_host_past_activities` - List past activities for a specific host\n- `fleet_get_host_mdm` - Get MDM information for a specific host\n- `fleet_list_host_certificates` - List certificates for a specific host\n- `fleet_get_host_macadmins` - Get macadmins data (Munki, MDM profiles) for a host\n- `fleet_get_host_device_mapping` - Get device mapping information for a host\n- `fleet_get_host_encryption_key` - Get disk encryption recovery key for a host\n\n#### Query Management\n- `fleet_list_queries` - List all saved queries with pagination\n- `fleet_get_query` - Get details of a specific saved query\n- `fleet_get_query_report` - Get the latest results from a scheduled query\n\n#### Policy Management\n- `fleet_list_policies` - List all compliance policies\n- `fleet_get_policy_results` - Get compliance results for a specific policy\n\n#### Software & Vulnerabilities\n- `fleet_list_software` - List software inventory across the fleet\n- `fleet_get_software` - Get detailed information about a specific software item\n- `fleet_get_host_software` - Get software installed on a specific host\n- `fleet_get_vulnerabilities` - List known vulnerabilities with filtering\n- `fleet_get_cve` - Get detailed information about a specific CVE\n- `fleet_search_software` - Search for software by name\n- `fleet_find_software_on_host` - Find specific software on a host by hostname\n- `fleet_get_software_install_result` - Get the result of a software installation request\n- `fleet_list_software_titles` - List software titles across the fleet\n- `fleet_get_software_title` - Get detailed information about a specific software title\n\n#### Team Management\n- `fleet_list_teams` - List all teams\n- `fleet_get_team` - Get details of a specific team\n- `fleet_list_team_users` - List all users that are members of a specific team\n- `fleet_get_team_secrets` - List team-specific enroll secrets\n\n#### User Management\n- `fleet_list_users` - List all users with filtering\n- `fleet_get_user` - Get details of a specific user\n- `fleet_list_user_sessions` - List active sessions for a user\n- `fleet_get_session` - Get session details by ID\n\n#### Label Management\n- `fleet_list_labels` - List all labels\n- `fleet_get_label` - Get detailed information about a specific label\n\n#### Pack Management\n- `fleet_list_packs` - List all query packs\n- `fleet_get_pack` - Get detailed information about a specific pack\n- `fleet_list_scheduled_queries` - List scheduled queries in a specific pack\n\n#### Script Management\n- `fleet_list_scripts` - List all scripts available in Fleet\n- `fleet_get_script` - Get details of a specific script\n- `fleet_get_script_result` - Get the result of a script execution\n- `fleet_list_batch_scripts` - List batch script executions\n- `fleet_get_batch_script` - Get details of a batch script execution\n- `fleet_list_batch_script_hosts` - List hosts in a batch script execution\n- `fleet_list_host_scripts` - List scripts available for a specific host\n\n#### MDM Management\n- `fleet_list_mdm_commands` - List MDM commands that have been executed\n- `fleet_get_mdm_command_results` - Get results of MDM commands\n- `fleet_list_mdm_profiles` - List MDM configuration profiles\n- `fleet_get_host_mdm_profiles` - Get MDM profiles installed on a specific host\n- `fleet_get_mdm_profiles_summary` - Get summary of MDM profile deployment status\n- `fleet_get_filevault_summary` - Get FileVault encryption summary\n- `fleet_list_mdm_devices` - List all MDM-enrolled Apple devices\n- `fleet_get_bootstrap_metadata` - Get metadata about a bootstrap package for a team\n- `fleet_get_bootstrap_summary` - Get aggregated summary about bootstrap package deployment\n- `fleet_get_setup_assistant` - Get the MDM Apple Setup Assistant configuration\n- `fleet_list_mdm_apple_installers` - List all Apple MDM installers\n\n#### VPP/App Store Management\n- `fleet_list_app_store_apps` - List App Store apps available for installation\n- `fleet_list_vpp_tokens` - List VPP tokens configured in Fleet\n\n#### Configuration Management\n- `fleet_get_config` - Get the current Fleet application configuration\n- `fleet_get_enroll_secrets` - Get the enrollment secrets configuration\n- `fleet_get_certificate` - Get the Fleet server certificate chain\n- `fleet_get_version` - Get the Fleet server version information\n\n#### Secret Management\n- `fleet_list_secrets` - List secret variables in Fleet\n\n#### Invite Management\n- `fleet_list_invites` - List pending user invites\n- `fleet_verify_invite` - Verify an invite token and get invite details\n\n#### Carve Management\n- `fleet_list_carves` - List file carve sessions\n- `fleet_get_carve` - Get detailed information about a specific carve session\n- `fleet_get_carve_block` - Get a specific block of data from a carve session\n\n#### Device Management\n- `fleet_get_device_info` - Get device information using a device token\n\n#### Activity Monitoring\n- `fleet_list_activities` - List Fleet activities and audit logs\n\n#### Osquery Table Discovery & Reference\n- `fleet_list_osquery_tables` - List available osquery tables with dynamic discovery\n- `fleet_get_osquery_table_schema` - Get detailed schema for a specific table\n- `fleet_suggest_tables_for_query` - Get AI-powered table suggestions based on intent\n\n#### System\n- `fleet_health_check` - Check Fleet server connectivity and authentication\n\n</details>\n\n<details>\n<summary><b>Write/Modify Tools (Requires <code>readonly=false</code>)</b></summary>\n\nThese tools can modify Fleet state and are only available when `readonly=false` is set in the configuration. This will allow you to make changes to your Fleet environment such as creating scripts, policies, managing teams, etc. in addition to the read-only tools. Setting to `readonly=true` (default) will disable these tools.\n\n#### Host Management\n- `fleet_delete_host` - Remove a host from Fleet\n- `fleet_transfer_hosts` - Transfer hosts to a different team\n- `fleet_query_host` - Run an ad-hoc live query against a specific host\n- `fleet_query_host_by_identifier` - Run a live query by hostname/UUID/serial\n- `fleet_cancel_host_activity` - Cancel an upcoming activity for a specific host\n- `fleet_lock_host` - Lock a host device remotely\n- `fleet_unlock_host` - Unlock a host device remotely\n- `fleet_unenroll_host_mdm` - Unenroll a host from MDM\n- `fleet_add_labels_to_host` - Add labels to a host\n- `fleet_remove_labels_from_host` - Remove labels from a host\n- `fleet_refetch_host` - Force a host to refetch and update its data immediately\n\n#### Query Management\n- `fleet_create_query` - Create a new saved query\n- `fleet_delete_query` - Delete a saved query\n- `fleet_run_live_query` - Execute a live query against specified hosts\n- `fleet_run_saved_query` - Run a saved query against hosts\n\n#### Policy Management\n- `fleet_create_policy` - Create a new compliance policy\n- `fleet_update_policy` - Update an existing policy\n- `fleet_delete_policy` - Delete a policy\n\n#### Software Management\n- `fleet_install_software` - Install software on a specific host\n- `fleet_batch_set_software` - Batch upload/set software installers for a team\n\n#### Team Management\n- `fleet_create_team` - Create a new team\n- `fleet_add_team_users` - Add one or more users to a specific team\n- `fleet_remove_team_user` - Remove a specific user from a team\n\n#### User Management\n- `fleet_create_user` - Create a new user\n- `fleet_update_user` - Update an existing user\n- `fleet_delete_session` - Delete/invalidate a specific session\n- `fleet_delete_user_sessions` - Delete all sessions for a specific user\n\n#### Label Management\n- `fleet_create_label` - Create a new label\n- `fleet_update_label` - Update an existing label\n- `fleet_delete_label` - Delete a label by name\n\n#### Pack Management\n- `fleet_create_pack` - Create a new query pack\n- `fleet_update_pack` - Update an existing pack\n- `fleet_delete_pack` - Delete a pack by name\n\n#### Script Management\n- `fleet_run_script` - Run a script on a specific host\n- `fleet_run_batch_script` - Run a script on multiple hosts\n- `fleet_cancel_batch_script` - Cancel a batch script execution\n- `fleet_create_script` - Create and upload a new script\n- `fleet_modify_script` - Modify an existing script\n- `fleet_delete_script` - Delete a script\n\n#### MDM Management\n- `fleet_upload_mdm_profile` - Upload a new MDM configuration profile\n- `fleet_delete_mdm_profile` - Delete an MDM configuration profile\n- `fleet_lock_device` - Lock an MDM-enrolled device remotely\n- `fleet_upload_bootstrap_package` - Upload a bootstrap package for MDM enrollment\n- `fleet_delete_bootstrap_package` - Delete a bootstrap package for a team\n- `fleet_create_setup_assistant` - Create or update an MDM Apple Setup Assistant\n- `fleet_delete_setup_assistant` - Delete the MDM Apple Setup Assistant\n- `fleet_upload_mdm_apple_installer` - Upload a new Apple MDM installer package\n**Note: The wipe device tool is currently disabled as it is too dangerous. It may be revisited later if really needed.**\n\n#### VPP/App Store Management\n- `fleet_add_app_store_app` - Add an App Store app for distribution\n- `fleet_update_app_store_app` - Update App Store app settings\n- `fleet_delete_vpp_token` - Delete a VPP token\n\n#### Configuration Management\n- `fleet_update_config` - Update the Fleet application configuration\n- `fleet_update_enroll_secrets` - Update the enrollment secrets configuration\n\n#### Secret Management\n- `fleet_create_secret` - Create a new secret variable\n- `fleet_delete_secret` - Delete a secret variable by ID\n\n#### Invite Management\n- `fleet_create_invite` - Create a new user invite\n- `fleet_update_invite` - Update a pending invite\n- `fleet_delete_invite` - Delete a pending invite\n\n</details>\n\n## Configuration\n\nFleet MCP supports three configuration methods (in order of precedence):\n\n1. **Command-line arguments** (highest priority)\n2. **Environment variables** (with `FLEET_` prefix)\n3. **Configuration file** (recommended for security)\n\n### Configuration File (Recommended)\n\nCreate `fleet-mcp.toml`:\n\n```toml\n[fleet]\nserver_url = \"https://your-fleet-instance.com\" # Required\napi_token = \"your-api-token\" # Required\nverify_ssl = true # Default: true\ntimeout = 30 # Default: 30 seconds\nmax_retries = 3 # Default: 3\nreadonly = true # Default: true\nallow_select_queries = false # Default: false\n```\n\n### Environment Variables\n\nSee [Configuration Options Reference](#configuration-options-reference) for all available variables. Environment variables use the `FLEET_` prefix and override config file settings.\n\n### Command-Line Arguments\n\n```bash\nfleet-mcp --server-url https://fleet.example.com --api-token YOUR_TOKEN run\n```\n\nOptions: `--config`, `--server-url`, `--api-token`, `--readonly`, `--verbose`\n\n## Read-Only Mode\n\nFleet MCP runs in **read-only mode by default** for safe exploration without risk of changes.\n\n### Three Operational Modes\n\n| Mode | Config | Capabilities | Best For |\n|------|--------|--------------|----------|\n| **Strict Read-Only** (Default) | `readonly=true`<br>`allow_select_queries=false` | \u2705 View all resources<br>\u274c No query execution<br>\u274c No modifications | Safe exploration |\n| **Read-Only + SELECT** | `readonly=true`<br>`allow_select_queries=true` | \u2705 View all resources<br>\u2705 Run SELECT queries<br>\u274c No modifications | Active monitoring |\n| **Full Write** | `readonly=false` | \u2705 All operations<br>\u26a0\ufe0f AI can modify Fleet | Full management |\n\n### Configuration Examples\n\n```toml\n# Strict Read-Only (Default)\n[fleet]\nreadonly = true\nallow_select_queries = false\n```\n```toml\n# Read-Only with SELECT Queries\n[fleet]\nreadonly = true\nallow_select_queries = true\n```\n```toml\n# Full Write Access (\u26a0\ufe0f Use with caution) - Recommended to have LLM prompt for confirmation before making changes\n[fleet]\nreadonly = false\n```\n\n## CLI Commands\n\n| Command | Description | Example |\n|---------|-------------|---------|\n| `run` | Start MCP server | `fleet-mcp run` |\n| `test` | Test Fleet connection | `fleet-mcp test` |\n| `init-config` | Create config template | `fleet-mcp init-config` |\n| `version` | Show version | `fleet-mcp version` |\n\n**Global Options:** `--config`, `--verbose`, `--server-url`, `--api-token`, `--readonly`\n\n## Usage Examples\n\n### Example 1: List All Teams\n```python\n# In Claude Desktop or any MCP client\n\"List all teams in Fleet\"\n```\n\n### Example 2: Find Software on a Host\n```python\n\"What version of Chrome is installed on host-123?\"\n```\n\n### Example 3: Run a Query\n```python\n# With allow_select_queries=true\n\"Run a query to find all processes listening on port 80\"\n```\n\n### Example 4: Check Compliance\n```python\n\"Show me which hosts are failing the disk encryption policy\"\n```\n\n### Example 5: Discover Osquery Tables\n```python\n\"What osquery tables are available for monitoring network connections?\"\n```\n\n## Development\n<details>\n<summary><b>Development Setup</b></summary>\n\nThis project uses [uv](https://docs.astral.sh/uv/) for dependency management.\n\n### Setup\n\n```bash\ngit clone https://github.com/SimplyMinimal/fleet-mcp.git\ncd fleet-mcp\nuv sync --dev\n```\n\n### Common Tasks\n\n| Task | Command |\n|------|---------|\n| Run tests | `uv run pytest` |\n| Format code | `uv run black src tests && uv run isort src tests` |\n| Type check | `uv run mypy src` |\n| Lint | `uv run ruff check src tests` |\n| Add dependency | `uv add package-name` |\n| Add dev dependency | `uv add --group dev package-name` |\n\n### Project Structure\n\n```\nsrc/fleet_mcp/\n\u251c\u2500\u2500 cli.py # Command-line interface\n\u251c\u2500\u2500 client.py # Fleet API client\n\u251c\u2500\u2500 config.py # Configuration management\n\u251c\u2500\u2500 server.py # MCP server implementation\n\u251c\u2500\u2500 tools/ # MCP tool implementations\n\u2514\u2500\u2500 utils/ # Utilities (SQL validator, etc.)\n```\n</details>\n\n## Troubleshooting\n\n<details>\n<summary><b>Server Not Appearing in Client</b></summary>\n\n1. Validate JSON syntax in config file\n2. Restart the MCP client\n3. Check client logs for errors\n4. Verify `uvx` or `fleet-mcp` is in PATH: `which uvx`\n\n</details>\n\n<details>\n<summary><b>Connection Errors</b></summary>\n\n1. Test manually: `uvx fleet-mcp test`\n2. Verify `FLEET_SERVER_URL` is accessible\n3. Check `FLEET_API_TOKEN` is valid\n4. For self-signed certs: `FLEET_VERIFY_SSL=false`\n\n</details>\n\n<details>\n<summary><b>Authentication Failed (401)</b></summary>\n\n1. Verify API token is correct\n2. Check token hasn't expired\n3. Ensure token has appropriate permissions\n4. Generate new token: Fleet UI \u2192 My account \u2192 Get API token\n\n</details>\n\n<details>\n<summary><b>Query Validation Failed</b></summary>\n\n1. Set `FLEET_ALLOW_SELECT_QUERIES=true`\n2. Ensure query is SELECT-only (no INSERT, UPDATE, DELETE, etc.)\n3. Verify osquery SQL syntax is valid\n\n</details>\n\n<details>\n<summary><b>Tool Not Available</b></summary>\n\n- Write operations require `FLEET_READONLY=false`\n- Query execution requires `FLEET_ALLOW_SELECT_QUERIES=true`\n- Check tool availability in current mode\n\n</details>\n\n## License\n\nFleet MCP is open source software licensed under the [MIT License](LICENSE).\n\nYou are free to use, modify, and distribute this software for any purpose, including commercial use, subject to the terms of the MIT License.\n\n## Disclaimer\n\nThis project is not affiliated with or endorsed by Fleet DM. It is an independent implementation of the Model Context Protocol for interacting with [Fleet](https://fleetdm.com) instances.\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "Model Context Protocol tool for Fleet DM integration",
"version": "1.0.2",
"project_urls": {
"Documentation": "https://github.com/SimplyMinimal/fleet-mcp#readme",
"Homepage": "https://github.com/SimplyMinimal/fleet-mcp",
"Issues": "https://github.com/SimplyMinimal/fleet-mcp/issues",
"Repository": "https://github.com/SimplyMinimal/fleet-mcp"
},
"split_keywords": [
"device-management",
" fleet",
" mcp",
" osquery",
" security"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "4d12d31072c6f359357a6f41734c1f4efc770f4353169fe49478cccc058704e3",
"md5": "e44a002d5bbf7b9a446a2b68065f6125",
"sha256": "ed36fbb41fe4ae2a1224412e60d94f1d53b0e0f32377e3924f4b011d01966e9e"
},
"downloads": -1,
"filename": "fleet_mcp-1.0.2-py3-none-any.whl",
"has_sig": false,
"md5_digest": "e44a002d5bbf7b9a446a2b68065f6125",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.10",
"size": 86426,
"upload_time": "2025-10-22T15:50:14",
"upload_time_iso_8601": "2025-10-22T15:50:14.389700Z",
"url": "https://files.pythonhosted.org/packages/4d/12/d31072c6f359357a6f41734c1f4efc770f4353169fe49478cccc058704e3/fleet_mcp-1.0.2-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "bf24dbb8a48f5032fdf4fe9377e5fb89e3c4bb353be5c1f8dd692fccf770b791",
"md5": "996cf8d5f9971a7754b7f327f241064e",
"sha256": "e587ea2228e90176d55eedff7757e97e3bd056723604adfa156e6c57fde730bc"
},
"downloads": -1,
"filename": "fleet_mcp-1.0.2.tar.gz",
"has_sig": false,
"md5_digest": "996cf8d5f9971a7754b7f327f241064e",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.10",
"size": 108507,
"upload_time": "2025-10-22T15:50:15",
"upload_time_iso_8601": "2025-10-22T15:50:15.951081Z",
"url": "https://files.pythonhosted.org/packages/bf/24/dbb8a48f5032fdf4fe9377e5fb89e3c4bb353be5c1f8dd692fccf770b791/fleet_mcp-1.0.2.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-10-22 15:50:15",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "SimplyMinimal",
"github_project": "fleet-mcp#readme",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "fleet-mcp"
}
JSON
