Qontinui Web

You can run and manage the Qontinui web MCP server to enable AI assistants to create, modify, and orchestrate visual automation configurations via the Qontinui API. This server handles projects, workflows, states, images, and execution, all through a configurable MCP interface that you run locally or in your environment.

How to use

You operate the MCP server with a client that can start the stdio process for the server. Start by ensuring your environment variables are set so the MCP server can talk to the Qontinui backend. Within your client, reference the MCP server you configured to handle projects, workflows, configurations, and executions. Use the server to create and manage projects, build workflows, define UI states with identifying images, and trigger runs of automations. You can import and export configurations to move between environments, and capture sessions to teach workflows from user actions.

How to install

cd qontinui-web-mcp
poetry install

Configuration and runtime basics

Set environment variables so the MCP server can reach the Qontinui API and authenticate your client requests.

# Development (local)
export QONTINUI_API_URL="http://localhost:8000"

# Production (AWS)
export QONTINUI_API_URL="http://qontinui-prod-py.eba-km2u4s23.eu-central-1.elasticbeanstalk.com"

# Authentication (obtain from Qontinui web app)
export QONTINUI_ACCESS_TOKEN="your-jwt-token"
# OR use credentials
export QONTINUI_EMAIL="your-email@example.com"
export QONTINUI_PASSWORD="your-password"

Running the MCP server with Claude Desktop or Claude Code

To connect Claude Desktop or Claude Code, configure the MCP server entry so it launches the server process with the required environment and command.

{
  "mcpServers": {
    "qontinui_web": {
      "command": "poetry",
      "args": ["run", "qontinui-web-mcp"],
      "env": {
        "QONTINUI_API_URL": "http://localhost:8000",
        "QONTINUI_EMAIL": "your-email@example.com",
        "QONTINUI_PASSWORD": "your-password"
      }
    }
  }
}

Additional usage notes

The MCP server is designed to work with the Qontinui backend to manage visual automation configurations. It exposes endpoints and tools to authenticate, manage projects and configurations, and execute workflows. Ensure you keep API access tokens secure and rotate credentials as needed.

How to configure deployment and environment variables

Configure the environment with the API URL and credentials before starting the server. If you run in production, point QONTINUI_API_URL to the production backend and supply credentials or an access token.

Security and best practices

Treat the access token and any credentials as sensitive information. Use a secure vault or environment management system in production. Restrict access to the MCP server and rotate keys periodically. When exporting configurations, ensure you do not include secrets unintentionally.

Development and testing

Install dependencies with Poetry, run tests, and format code as part of your development workflow.

# Install dependencies
poetry install

# Run tests
poetry run pytest

# Format code
poetry run black src/
poetry run isort src/

# Lint
poetry run ruff src/

# Type check
poetry run mypy src/

API endpoints and server communication

This MCP server communicates with the Qontinui backend API to manage configurations and trigger executions. Use your backend URL to connect and authenticate as needed.

Available tools

auth_login

Authenticate with email/password to obtain and store a session or token for subsequent MCP operations.

auth_status

Check the current authentication status and token validity.

auth_logout

Clear stored credentials and end the session.

list_projects

List all projects accessible to the authenticated user.

create_project

Create a new project with initial metadata and configuration.

get_project

Retrieve details of a specific project.

update_project

Update metadata or configuration of an existing project.

delete_project

Delete a project and its associated data.

export_configuration

Export the project configuration as JSON for backup or transfer.

import_configuration

Import a project configuration from JSON into the selected project.

validate_configuration

Validate a configuration without applying it to the project.

create_workflow

Add a new workflow to a project.

update_workflow

Modify an existing workflow in a project.

delete_workflow

Remove a workflow from a project.

list_workflows

List all workflows within a project.

create_state

Define a UI state with identifying images.

update_state

Update an existing UI state.

delete_state

Remove a UI state from a project.

list_states

List all UI states in a project.

add_image

Add pattern image data to a project for state recognition.

list_images

List all images stored for a project.

delete_image

Remove an image from a project.

execute_workflow

Run a workflow on the connected runner.

get_execution_status

poll the progress of a running workflow execution.

cancel_execution

Cancel a currently running workflow execution.