Skip to main content

qfield-mcp

MCP server that starts stock QField AppImages on private displays and lets an agent look at the screen, tap, type and run JavaScript inside QField. Built on qfield-driver.

Requirements

  • Linux x64 with Xvfb, the system libraries the QField AppImage does not bundle and util-linux unshare, see the qfield-driver requirements
  • uv
  • For the cloud tools: docker or rootless podman with docker compose, and git

Install

Run it with uvx, which installs the package into an isolated environment on first use:

claude mcp add qfield -- uvx qfield-mcp
  • Pin a release with uvx qfield-mcp@0.1.0, update a cached one with uvx qfield-mcp@latest.
  • claude mcp add --scope project qfield -- uvx qfield-mcp writes the server into the repository's .mcp.json, so everyone working on your plugin gets it.
  • If uv picks a Python that the dependencies have no wheels for yet, add --python 3.12 after uvx.

Other MCP clients take the same command:

{
  "mcpServers": {
    "qfield": {"command": "uvx", "args": ["qfield-mcp"]}
  }
}

Configuration

AppImages come from the qfield-fetch cache, ~/.cache/qfield-fetch unless QFIELD_FETCH_CACHE_DIR is set. The first start_device of a release downloads it. These variables of the server's environment apply when a tool call names no version or ref:

Variable What
QFIELD_APP_BINARY An AppRun, an AppImage or a build of your own instead of release 4.2.9. start_device fails naming it when the path is not executable, pass version or unset it
QFIELDCLOUD_SOURCE_DIR A QFieldCloud checkout of your own for cloud_up instead of the hosted release
QFIELDCLOUD_PORT_OFFSET Moves every port and the compose project of cloud_up and cloud_attach, so stacks of parallel checkouts do not collide
claude mcp add qfield -e QFIELD_APP_BINARY=/path/to/AppRun -- uvx qfield-mcp

Tools

  • start_device, stop_device, list_devices: one QField per device name, with its own profile, display and fake GNSS receiver. start_device can host a plugin directory and open a project. reload_plugin loads the hosted plugin again with your edits.
  • find_items, item_tree: visible items with object names, texts, [clickable] and window positions. Both can list only clickable items.
  • wait_for: until a JS body is truthy, or a text appears or disappears.
  • tap, tap_map, frame_map, type_text, key: real input events.
  • screenshot: the window or one item as PNG, optionally scaled down. Refused while a camera view is open.
  • eval_js: a JS function body run inside QField. Its description lists where QML differs from PyQGIS.
  • messages, log: QField's message log and process output.
  • open_project, set_position, features: open a project, feed a GNSS fix, read attributes.
  • open_feature_form, set_field, save_form, close_feature_form: edit through the real form. set_field and save_form use whichever form is open, an existing feature's or a new one's.
  • set_active_layer, digitize_point, add_feature, change_geometry, delete_feature: add a point by tapping the map, add one in code, move one and delete one through its form menu.
  • cloud_up, cloud_attach, cloud_status, cloud_login, cloud_download, cloud_synchronize: a local QFieldCloud and devices synced with it. cloud_up takes port_offset and name, and refuses a running compose project this server did not configure. cloud_attach takes those and https_port and only checks that the stack answers and that the named compose project owns its URL, so it also picks up a stack some other run started, an e2e run's for example, and it brings the tools back after a server restart. cloud_up and cloud_attach print the URL, cloud_status shows it later. cloud_login uses that URL when given none. cloud_download can answer a project plugin's permission prompt, and cloud_synchronize reports how many deltas went up and their status.
  • cloud_user, cloud_create_project, cloud_add_collaborator, cloud_upload, cloud_package, cloud_deltas: set up users and projects on the cloud cloud_up started, and read the deltas a project received. They act as the admin unless given username and password. A login ends the same user's other sessions, so give each device a user of its own.

Calls to one device run one at a time. Devices stop when the server exits, and a server that was killed has its devices stopped by the next server start.

Development

To run the server from a checkout of qfield-dev-tools, see DEVELOPMENT.md.

Metadata

Release files for qfield-mcp 0.2.0

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for qfield-mcp 0.2.0
File Size Uploaded Provenance Actions
qfield_mcp-0.2.0.tar.gz 23.4 kB Without provenance Details for qfield_mcp-0.2.0.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for qfield-mcp 0.2.0
File Interpreter ABI Platform Actions
qfield_mcp-0.2.0-py3-none-any.whl Python 3 none any Details for qfield_mcp-0.2.0-py3-none-any.whl

Total release size: 46.9 kB

Release files / qfield_mcp-0.2.0.tar.gz

Download URL qfield_mcp-0.2.0.tar.gz
Size 23.4 kB
Tags Source
SHA-256 checksum
How to use checksums
5782cdd0a396b5b42a72093f74f359531dfbc101298de6eaf7366685e6beb64d
BLAKE2b-256 checksum
How to use checksums
3d8f3b1c27aa98293b165b2c087d48a3f236d9d8d40464fc1ea911456a8abe45
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via uv/0.13.8 {"installer":{"name":"uv","version":"0.13.8","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Ubuntu","version":"26.04","id":"resolute","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":true}

Release files / qfield_mcp-0.2.0-py3-none-any.whl

Download URL qfield_mcp-0.2.0-py3-none-any.whl
Size 23.5 kB
Tags Python 3
SHA-256 checksum
How to use checksums
6046585d2d55e0cbf333906d872e21b16a31d52478c33abde7d6d8d023ab99ca
BLAKE2b-256 checksum
How to use checksums
14ff5fe08d265bad2e20e0d6f8f7b337bb34ae797933fd9255248275ece09637
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via uv/0.13.8 {"installer":{"name":"uv","version":"0.13.8","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Ubuntu","version":"26.04","id":"resolute","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":true}

Security for qfield-mcp 0.2.0

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

No provenance found

None of the files in this release were uploaded with provenance metadata.

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page