wiki/monitor-mcp/Configuration.md

← Back to Home

Configuration

monitor-mcp loads its configuration from ~/.monitor-mcp.json (or the path set in MONITOR_MCP_CONFIG environment variable).

Config File Location

Method	Path
Default	~/.monitor-mcp.json
Environment variable	MONITOR_MCP_CONFIG=/path/to/config.json

Config File Structure

{
  "defaultConnection": "production",
  "connections": {
    "production": {
      "host": "server.example.com",
      "port": 22,
      "username": "deploy",
      "keyPath": "~/.ssh/id_ed25519"
    },
    "staging": {
      "host": "staging.example.com",
      "username": "deploy",
      "keyPath": "~/.ssh/id_ed25519"
    }
  },
  "grafana": {
    "baseUrl": "https://grafana.example.com",
    "apiKey": "glsa_xxxxxxxxxxxx"
  },
  "sitesJsonPath": "/path/to/sites.json"
}

Top-Level Fields

Field	Type	Required	Description
connections	Record<string, MonitorConnection>	Yes	Named SSH server connections
defaultConnection	string	No	Default connection name. Falls back to the first key in connections
grafana	GrafanaConfig	No	Grafana instance configuration
sitesJsonPath	string	No	Path to a sites.json file for site inventory management

Connection Fields

Each entry in connections defines an SSH target server.

Field	Type	Required	Default	Description
host	string	Yes	—	Hostname or IP address
port	number	No	22	SSH port
username	string	Yes	—	SSH login user
keyPath	string	No	—	Path to SSH private key file

Grafana Fields

The grafana block enables Grafana monitoring tools (grafana_health, grafana_dashboards, grafana_alerts, etc.).

Field	Type	Required	Description
baseUrl	string	Yes	Grafana instance URL (e.g. https://grafana.example.com)
apiKey	string	Yes	Grafana service account token (Bearer auth)

Both baseUrl and apiKey must be present for Grafana tools to activate. If omitted, all Grafana tools return "Grafana not configured".

Grafana from sites.json

If sitesJsonPath is set and the sites.json file contains a top-level grafana block, monitor-mcp will use it as a fallback when grafana is not set directly in the config file.

sitesJsonPath

Points to a sites.json file that defines monitored sites. This enables the monitor_sites, monitor_site_add, and monitor_site_remove tools.

sites.json Format

{
  "grafana": {
    "baseUrl": "https://grafana.example.com",
    "apiKey": "glsa_xxxxxxxxxxxx",
    "dashboardFolder": "Sites",
    "dashboardFolderUid": "abc123"
  },
  "sites": [
    {
      "name": "mysite-live",
      "url": "https://example.com",
      "type": "joomla",
      "client": "Example Corp",
      "joomlaToken": "tok_xxxx",
      "akeebaSecret": "secret123",
      "tlsVerify": true
    }
  ]
}

Site Definition Fields

Field	Type	Required	Description
name	string	Yes	Unique site identifier (e.g. mysite-live, mysite-dev)
url	string	Yes	Site URL
type	string	Yes	Site type: joomla, dolibarr, gitea, grafana, generic
client	string	Yes	Client name label
joomlaToken	string	No	Joomla API token
dolibarrToken	string	No	Dolibarr API token
akeebaSecret	string	No	Akeeba Backup frontend secret word
tlsVerify	boolean	No	Verify TLS certificates (default true)

Minimal Config Example

The simplest valid configuration with a single server:

{
  "connections": {
    "myserver": {
      "host": "192.168.1.100",
      "username": "admin"
    }
  }
}

---

Built on MokoStandards

---

Repo: monitor-mcp · MokoStandards

Revision	Date	Author	Description
1.0	2026-05-09	Moko Consulting	Initial version