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. 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_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. 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_fieldandsave_formuse 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_uptakesport_offsetandname, and refuses a running compose project this server did not configure.cloud_attachtakes those andhttps_portand 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_upandcloud_attachprint the URL,cloud_statusshows it later.cloud_loginuses that URL when given none.cloud_downloadcan answer a project plugin's permission prompt, andcloud_synchronizereports 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 cloudcloud_upstarted, and read the deltas a project received. They act as the admin unless givenusernameandpassword. 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)
| 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)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| 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.