# ignition-mcp
A **Model Context Protocol (MCP)** server that gives AI assistants a curated,
developer-oriented interface to the **Ignition Gateway REST API**.
Built on [FastMCP](https://github.com/jlowin/fastmcp) with 37 hand-crafted tools
covering gateway management, projects, resources, tag providers, tags, alarms,
tag history, and script execution.
## Tools
| Category | Tools | Backend |
|----------|-------|---------|
| Gateway (6) | `get_gateway_info`, `get_module_health`, `get_gateway_logs`, `get_database_connections`, `get_opc_connections`, `get_system_metrics` | Native REST |
| Projects (8) | `list_projects`, `get_project`, `create_project`, `delete_project`, `copy_project`, `rename_project`, `export_project`, `import_project` | Native REST |
| Project Resources (4) | `list_project_resources`, `get_project_resource`, `set_project_resource`, `delete_project_resource` | Native REST |
| Designers (1) | `list_designers` | Native REST |
| Tag Providers (4) | `list_tag_providers`, `get_tag_provider`, `create_tag_provider`, `delete_tag_provider` | Native REST |
| Tag Browse (1) | `browse_tags` | Native REST |
| Tag Values (2) | `read_tags`, `write_tag` | WebDev |
| Tag Config (6) | `get_tag_config`, `create_tags`, `edit_tags`, `delete_tags`, `list_udt_types`, `get_udt_definition` | WebDev |
| Alarms (3) | `get_active_alarms`, `get_alarm_history`, `acknowledge_alarms` | WebDev |
| Historian (1) | `get_tag_history` | WebDev |
| Script Execution (1) | `run_gateway_script` (disabled by default) | WebDev |
## Requirements
- Python 3.10+
- Ignition Gateway 8.3+ with REST API enabled
- Gateway credentials (API key preferred) or basic auth
## Setup
```bash
# Install
uv sync
# Configure
cp .env.example .env
# Edit .env with your gateway URL and credentials
```
### Environment Variables
All environment variables are prefixed with `IGNITION_MCP_`:
| Variable | Default | Description |
|----------|---------|-------------|
| `IGNITION_MCP_IGNITION_GATEWAY_URL` | `http://localhost:8088` | Gateway base URL |
| `IGNITION_MCP_IGNITION_API_KEY` | *(empty)* | API key auth (preferred over basic auth) |
| `IGNITION_MCP_IGNITION_USERNAME` | `admin` | Basic auth username |
| `IGNITION_MCP_IGNITION_PASSWORD` | `password` | Basic auth password |
| `IGNITION_MCP_SSL_VERIFY` | `true` | Set `false` for self-signed certs |
| `IGNITION_MCP_WEBDEV_TAG_ENDPOINT` | *(empty)* | WebDev path for `read_tags`/`write_tag` |
| `IGNITION_MCP_WEBDEV_TAG_CONFIG_ENDPOINT` | *(empty)* | WebDev path for tag CRUD |
| `IGNITION_MCP_WEBDEV_ALARM_ENDPOINT` | *(empty)* | WebDev path for alarm tools |
| `IGNITION_MCP_WEBDEV_TAG_HISTORY_ENDPOINT` | *(empty)* | WebDev path for `get_tag_history` |
| `IGNITION_MCP_WEBDEV_SCRIPT_EXEC_ENDPOINT` | *(empty)* | WebDev path for `run_gateway_script` |
| `IGNITION_MCP_ENABLE_SCRIPT_EXECUTION` | `false` | Set `true` to enable `run_gateway_script` |
| `IGNITION_MCP_SERVER_HOST` | `127.0.0.1` | MCP server bind host |
| `IGNITION_MCP_SERVER_PORT` | `8007` | MCP server port |
## Running
```bash
# Streamable HTTP (default) — http://localhost:8007/mcp
uv run python mcp_server.py
# stdio transport (for Claude Desktop subprocess mode)
uv run python mcp_server.py --transport stdio
```
## Client Configuration
### Claude Code (`.mcp.json`)
```json
{
"mcpServers": {
"ignition-mcp": {
"type": "streamable-http",
"url": "http://localhost:8007/mcp"
}
}
}
```
### Claude Desktop (`claude_desktop_config.json`)
```json
{
"mcpServers": {
"ignition-mcp": {
"command": "uv",
"args": ["run", "python", "mcp_server.py", "--transport", "stdio"],
"cwd": "/path/to/ignition-mcp",
"env": {
"IGNITION_MCP_IGNITION_GATEWAY_URL": "https://your-gateway:8043",
"IGNITION_MCP_IGNITION_API_KEY": "your-api-key"
}
}
}
}
```
## WebDev Prerequisite (tag values, alarms, history, script execution)
Several tools require **WebDev module scripts** deployed on the target Ignition gateway.
The native REST API (`/data/api/v1/`) only covers configuration — it does not support
runtime tag reads/writes, alarm queries, historian, or script execution.
Tools that require WebDev endpoints:
- **Tag values**: `read_tags`, `write_tag` → `IGNITION_MCP_WEBDEV_TAG_ENDPOINT`
- **Tag CRUD**: `get_tag_config`, `create_tags`, `edit_tags`, `delete_tags`, `list_udt_types`, `get_udt_definition` → `IGNITION_MCP_WEBDEV_TAG_CONFIG_ENDPOINT`
- **Alarms**: `get_active_alarms`, `get_alarm_history`, `acknowledge_alarms` → `IGNITION_MCP_WEBDEV_ALARM_ENDPOINT`
- **Historian**: `get_tag_history` → `IGNITION_MCP_WEBDEV_TAG_HISTORY_ENDPOINT`
- **Script execution**: `run_gateway_script` → `IGNITION_MCP_WEBDEV_SCRIPT_EXEC_ENDPOINT` + `IGNITION_MCP_ENABLE_SCRIPT_EXECUTION=true`
If a WebDev endpoint is not configured, the relevant tools return a clear error with setup instructions.
See [docs/webdev-setup.md](docs/webdev-setup.md) for gateway-side deployment scripts.
## Testing
```bash
# Unit tests (no live gateway needed)
uv run pytest tests/ -v
# Integration tests (requires running Ignition gateway)
RUN_LIVE_GATEWAY_TESTS=1 uv run pytest tests/test_integration.py -v
```
## Architecture
```text
mcp_server.py # FastMCP entry point, lifespan, arg parsing
src/ignition_mcp/
config.py # Pydantic Settings (IGNITION_MCP_ prefix)
ignition_client.py # Async HTTP client (httpx) for Gateway REST + WebDev
tools/
__init__.py # register_all(mcp) — calls each module
gateway.py # info, health, logs, connections, metrics
projects.py # project CRUD + export/import
resources.py # project resource CRUD (native REST)
designers.py # list_designers
tag_providers.py # tag provider CRUD
tags.py # browse + read/write + CRUD via WebDev
alarms.py # alarm query + ack (WebDev)
historian.py # tag history (WebDev)
execution.py # run_gateway_script (off by default)
tests/
conftest.py # Shared fixtures
test_client.py # IgnitionClient unit tests (mocked httpx)
test_tools.py # Tool logic unit tests (mocked client)
test_integration.py # Live gateway tests (skipped by default)
docs/
webdev-setup.md # WebDev script deployment guide
api-reference.md # Full tool reference
```
## License
MIT
