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
QFIELDCLOUD_SOURCE_DIR A QFieldCloud checkout of your own for cloud_up instead of the hosted release
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.
  • messages, log: QField's message log and process output.
  • open_project, set_position, features, open_feature_form, set_field, save_form, close_feature_form.
  • cloud_up, cloud_login, cloud_download, cloud_synchronize: a local QFieldCloud and devices synced with it.

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.1.1

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.1.1
File Size Uploaded Provenance Actions
qfield_mcp-0.1.1.tar.gz 19.1 kB Without provenance Details for qfield_mcp-0.1.1.tar.gz

Built distribution (wheel)

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

Total release size: 38.9 kB

Release files / qfield_mcp-0.1.1.tar.gz

Download URL qfield_mcp-0.1.1.tar.gz
Size 19.1 kB
Tags Source
SHA-256 checksum
How to use checksums
0c4c374dcaa9f2916223173757c0c05329bb3d31214baef9a7d2b8a9bb485865
BLAKE2b-256 checksum
How to use checksums
de57c8e5c51b5600567c8dcd2b3ca4e5dfbc923c01661789d850847ec530e5cc
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.1.1-py3-none-any.whl

Download URL qfield_mcp-0.1.1-py3-none-any.whl
Size 19.8 kB
Tags Python 3
SHA-256 checksum
How to use checksums
7ab2d6cc8c64a3af1a0d0b9e9f40d9ae5c9cf129d7a462038b43340c900eabe8
BLAKE2b-256 checksum
How to use checksums
9f30ae25fa54c16f98c507a623d734f27f2efff596cfedf431bb3356c343db7f
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.1.1

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