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, andgit
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 withuvx qfield-mcp@latest. claude mcp add --scope project qfield -- uvx qfield-mcpwrites 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.12afteruvx.
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_devicecan host a plugin directory and open a project.reload_pluginloads 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.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| qfield_mcp-0.1.0.tar.gz | 19.1 kB | Without provenance | Details for qfield_mcp-0.1.0.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| qfield_mcp-0.1.0-py3-none-any.whl | Python 3 | none | any | Details for qfield_mcp-0.1.0-py3-none-any.whl |
Total release size: 38.9 kB
Release files / qfield_mcp-0.1.0.tar.gz
| Download URL | qfield_mcp-0.1.0.tar.gz |
|---|---|
| Size | 19.1 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
0f50178087dafdf9824c77838921d2cf23e546f20f17fb1564144bd21aadaa2f
|
|
BLAKE2b-256 checksum How to use checksums |
b9fdd31694048297ac659b59e5e02096d614a0010162a9af9f0fc503c571fbdf
|
| 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.0-py3-none-any.whl
| Download URL | qfield_mcp-0.1.0-py3-none-any.whl |
|---|---|
| Size | 19.8 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
e468d4fe221f2a7e441d0e0d679763eec68525cc09360f540d0a5d862ff5591e
|
|
BLAKE2b-256 checksum How to use checksums |
8972120898c42dc9d619174da1b5c80872ca91f995d66a5ccc7f5ac1a8eb7eb1
|
| 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.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.