[← Back to Home](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

```json
{
  "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

```json
{
  "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:

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

---

> Built on [MokoStandards](https://git.mokoconsulting.tech/MokoConsulting/MokoStandards-API)

---

*Repo: [monitor-mcp](https://git.mokoconsulting.tech/MokoConsulting/monitor-mcp) · [MokoStandards](https://git.mokoconsulting.tech/MokoConsulting/moko-platform/wiki/Home)*

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