Skip to content

tools.md

Latest commit

 

History

History
625 lines (478 loc) · 11.9 KB

tools.md

File metadata and controls

625 lines (478 loc) · 11.9 KB

MCP Tools Reference

Complete reference for all available MCP tools in the OPNSense MCP Server.

Tool Categories

Configuration

configure

Configure OPNsense connection settings.

Parameters:

Name Type Required Description
host string Yes OPNsense host URL
apiKey string Yes API key
apiSecret string Yes API secret
verifySsl boolean No Verify SSL certificate (default: true)

Example:

await configure({
  host: "https://192.168.1.1",
  apiKey: "your_api_key",
  apiSecret: "your_api_secret",
  verifySsl: false
});

Returns: Configuration status

Network Management

listVlans

List all configured VLANs.

Parameters: None

Returns:

[{
  uuid: "string",
  interface: "igc3",
  tag: 50,
  description: "Guest Network",
  device: "igc3_vlan50"
}]

createVlan

Create a new VLAN.

Parameters:

Name Type Required Description
interface string Yes Physical interface (e.g., "igc3")
tag number Yes VLAN tag (1-4094)
description string No VLAN description
priority number No 802.1p priority (0-7)

Example:

await createVlan({
  interface: "igc3",
  tag: 50,
  description: "Guest WiFi"
});

Returns: Created VLAN details

deleteVlan

Delete a VLAN.

Parameters:

Name Type Required Description
uuid string Yes VLAN UUID

Returns: Deletion status

listInterfaces

List network interfaces.

Parameters: None

Returns:

[{
  name: "igc0",
  description: "WAN",
  status: "up",
  ipAddress: "203.0.113.1",
  macAddress: "aa:bb:cc:dd:ee:ff"
}]

Firewall Management

listFirewallRules

List firewall rules.

Parameters:

Name Type Required Description
interface string No Filter by interface
direction string No "in" or "out"

Returns:

[{
  uuid: "string",
  interface: "wan",
  action: "pass",
  protocol: "tcp",
  source: "any",
  destination: "192.168.1.100",
  port: "443",
  description: "Allow HTTPS"
}]

createFirewallRule

Create a firewall rule.

Parameters:

Name Type Required Description
interface string Yes Interface name
action string Yes "pass", "block", or "reject"
direction string No "in" or "out" (default: "in")
protocol string No Protocol (tcp, udp, icmp, any)
source object No Source address and port
destination object No Destination address and port
description string No Rule description
log boolean No Enable logging

Example:

await createFirewallRule({
  interface: "wan",
  action: "pass",
  protocol: "tcp",
  destination: {
    address: "192.168.1.100",
    port: "80,443"
  },
  description: "Allow web traffic"
});

updateFirewallRule

Update existing firewall rule.

Parameters:

Name Type Required Description
uuid string Yes Rule UUID
...props object No Properties to update

deleteFirewallRule

Delete firewall rule.

Parameters:

Name Type Required Description
uuid string Yes Rule UUID

createAlias

Create firewall alias.

Parameters:

Name Type Required Description
name string Yes Alias name
type string Yes "host", "network", "port", or "url"
content array Yes List of values
description string No Description

Example:

await createAlias({
  name: "web_servers",
  type: "host",
  content: ["192.168.1.10", "192.168.1.11"],
  description: "Web server pool"
});

Service Management

listDhcpLeases

List DHCP leases.

Parameters:

Name Type Required Description
interface string No Filter by interface
state string No "active", "expired", or "all"

Returns:

[{
  ip: "192.168.1.100",
  mac: "aa:bb:cc:dd:ee:ff",
  hostname: "laptop",
  starts: "2024-01-15 10:00:00",
  ends: "2024-01-15 22:00:00",
  state: "active"
}]

configureDhcpServer

Configure DHCP server.

Parameters:

Name Type Required Description
interface string Yes Interface name
enable boolean Yes Enable/disable DHCP
range object Yes IP range (from, to)
gateway string No Default gateway
dns array No DNS servers
domain string No Domain name
leaseTime number No Lease time in seconds

Example:

await configureDhcpServer({
  interface: "lan",
  enable: true,
  range: {
    from: "192.168.1.100",
    to: "192.168.1.200"
  },
  gateway: "192.168.1.1",
  dns: ["192.168.1.1", "8.8.8.8"],
  leaseTime: 86400
});

createStaticMapping

Create DHCP static mapping.

Parameters:

Name Type Required Description
mac string Yes MAC address
ip string Yes IP address
hostname string No Hostname
description string No Description

Device Discovery

listArpTable

List ARP table entries.

Parameters:

Name Type Required Description
interface string No Filter by interface

Returns:

[{
  ip: "192.168.1.100",
  mac: "aa:bb:cc:dd:ee:ff",
  interface: "lan",
  type: "dynamic",
  manufacturer: "Apple Inc."
}]

findDevicesByName

Find devices by hostname.

Parameters:

Name Type Required Description
search string Yes Search term
source string No "arp", "dhcp", or "all"

Example:

await findDevicesByName({
  search: "laptop"
});

findDeviceByMac

Find device by MAC address.

Parameters:

Name Type Required Description
mac string Yes MAC address

findDeviceByIp

Find device by IP address.

Parameters:

Name Type Required Description
ip string Yes IP address

DNS Management

blockDomains

Block domains in DNS.

Parameters:

Name Type Required Description
domains array Yes List of domains to block
description string No Block description

Example:

await blockDomains({
  domains: ["facebook.com", "twitter.com"],
  description: "Social media block"
});

unblockDomains

Remove domain blocks.

Parameters:

Name Type Required Description
domains array Yes Domains to unblock

listBlockedDomains

List blocked domains.

Parameters:

Name Type Required Description
search string No Search term

applyBlocklistCategory

Apply predefined blocklist.

Parameters:

Name Type Required Description
category string Yes Category name

Categories:

  • adult - Adult content
  • social - Social media
  • ads - Advertising
  • malware - Malicious sites
  • gambling - Gambling sites

HAProxy Management

haproxy_service_control

Control HAProxy service.

Parameters:

Name Type Required Description
action string Yes "start", "stop", "restart", "reload", or "status"

haproxy_backend_create

Create HAProxy backend.

Parameters:

Name Type Required Description
name string Yes Backend name
mode string Yes "http" or "tcp"
balance string Yes Load balancing algorithm
servers array No Backend servers
description string No Description

Balance algorithms:

  • roundrobin - Round robin
  • leastconn - Least connections
  • source - Source IP hash
  • uri - URI hash
  • random - Random

Server object:

{
  name: "web1",
  address: "192.168.1.10",
  port: 80,
  ssl: false,
  check: true,
  weight: 1
}

haproxy_frontend_create

Create HAProxy frontend.

Parameters:

Name Type Required Description
name string Yes Frontend name
bind string Yes Bind address (e.g., "0.0.0.0:443")
mode string Yes "http" or "tcp"
backend string Yes Default backend
ssl boolean No Enable SSL
certificates array No SSL certificates

haproxy_stats

Get HAProxy statistics.

Parameters: None

Returns:

{
  frontends: [{
    name: "string",
    status: "UP",
    sessions: 10,
    bytesIn: 1024000,
    bytesOut: 2048000
  }],
  backends: [{
    name: "string",
    status: "UP",
    activeServers: 3,
    backupServers: 1,
    sessions: 25
  }]
}

Backup & System

createBackup

Create configuration backup.

Parameters:

Name Type Required Description
description string No Backup description
type string No "full" or "partial"
components array No Components to backup (partial only)

Example:

await createBackup({
  description: "Before upgrade",
  type: "full"
});

listBackups

List available backups.

Parameters: None

Returns:

[{
  filename: "config-2024-01-15.xml",
  date: "2024-01-15T10:00:00Z",
  size: 102400,
  description: "Before upgrade"
}]

restoreBackup

Restore from backup.

Parameters:

Name Type Required Description
filename string Yes Backup filename
components array No Components to restore

getSystemInfo

Get system information.

Parameters: None

Returns:

{
  version: "23.7",
  hostname: "opnsense.local",
  uptime: "5 days",
  cpuUsage: 15,
  memoryUsage: 45,
  diskUsage: 30
}

Common Patterns

Error Handling

All tools follow consistent error handling:

try {
  const result = await createVlan({
    interface: "igc3",
    tag: 50
  });
} catch (error) {
  // error.code - Error code
  // error.message - Error description
  // error.details - Additional details
}

Pagination

List operations support pagination:

await listFirewallRules({
  page: 1,
  limit: 50,
  sort: "description"
});

Filtering

Most list operations support filtering:

await listDhcpLeases({
  interface: "lan",
  state: "active",
  search: "laptop"
});

Batch Operations

Some tools support batch operations:

await blockDomains({
  domains: [
    "site1.com",
    "site2.com",
    "site3.com"
  ]
});

Rate Limiting

The MCP server implements rate limiting:

  • Default: 100 requests per minute
  • Burst: 10 concurrent requests
  • Retry with backoff on rate limit

Authentication

All tools use the configured OPNsense API credentials:

  • Set via environment variables
  • Or configured with configure tool
  • Credentials are securely stored

Next Steps