farmos-mcp

An MCP server for farmOS 4. It lets an AI assistant look up and record farm data (assets, logs, plans, quantities, taxonomy terms) through farmOS's JSON:API.

It was written against the farmOS 4.0 API changes: assets use the archived boolean instead of a status, plans have planning / active / done / abandoned statuses, and logs can be abandoned. On a farmOS 3 server it falls back to the old status handling for archiving.

Early release (v0.1.0, alpha). Unit-tested against a mock farmOS server, but not yet run against a live farmOS instance. Expect rough edges and possible breaking changes. Try it on a test or demo instance first (see "Verify against your server" below), and do not point write access at production data you can't restore.

Built with AI. This project was written by an AI assistant (Claude, by Anthropic) working with a human maintainer. See AI disclosure.

Tools

Related MCP server: drupal-mcp

Safety defaults

• Read-only by default. Writes need FARMOS_ALLOW_WRITES=true. Deletes additionally need FARMOS_ALLOW_DELETE=true.

• Writes are limited to asset, log, plan, quantity, taxonomy_term and organization. Users, roles and configuration cannot be written through this server.

• Credentials are only sent to the configured FARMOS_URL. Pagination links pointing at another host are refused. Plain http:// is rejected for non-local hosts.

• Everything the assistant can do is bounded by the farmOS account it logs in as. Use a dedicated account with the lowest role that does the job (see Roles below).

farmOS setup

farmOS 4 made the API and OAuth2 server optional, so check these on your instance:

1. Enable the API module (farm_api) and the OAuth2 server module (farm_api_oauth) under Administration > Modules (or drush en farm_api farm_api_oauth).

2. Create OAuth2 keys. farmOS 4 no longer generates them at install. See OAuth2 keys.

3. Pick an auth method:

   • Password grant (simplest). Uses the built-in farm client with a farmOS username and password. This is a legacy grant type: it also requires the simple_oauth_password_grant module, and is only appropriate when the MCP server is a trusted first-party client on your own machine.

   • Client credentials (better for unattended use). Create a client (consumer) in farmOS with a secret and the client credentials grant, mapped to a user. Set FARMOS_CLIENT_ID and FARMOS_CLIENT_SECRET.

Roles

farmOS 4 split the default roles into separate modules and changed what they can do:

• Viewer: read-only. Right for a read-only deployment.

• Worker: can create and edit records, but in v4 can no longer delete other users' records or edit/delete taxonomy terms.

• Manager: full records access including terms and deletes.

The OAuth scope must match a role the user has. The default scope here is farm_manager; change FARMOS_SCOPE to farm_worker or farm_viewer for a narrower token.

Install

cd farmos-mcp
python3 -m venv .venv
.venv/bin/pip install -e .

Requires Python 3.11+ and mcp 2.x (this project uses the 2.x MCPServer API).

Configure

Environment variables (see .env.example):

If a password is set it wins; otherwise a client secret selects the client credentials grant.

Claude Desktop / Claude Code

{
  "mcpServers": {
    "farmos": {
      "command": "/absolute/path/to/farmos-mcp/.venv/bin/farmos-mcp",
      "env": {
        "FARMOS_URL": "https://farm.example.com",
        "FARMOS_USERNAME": "claude-assistant",
        "FARMOS_PASSWORD": "...",
        "FARMOS_SCOPE": "farm_worker",
        "FARMOS_ALLOW_WRITES": "false"
      }
    }
  }
}

For Claude Code: claude mcp add farmos --env FARMOS_URL=https://farm.example.com --env FARMOS_USERNAME=... --env FARMOS_PASSWORD=... -- /absolute/path/to/farmos-mcp/.venv/bin/farmos-mcp

Verify against your server

Do these in order against a test instance (the public demo is a reasonable target for reads):

1. Ask for farm_info. You should see version 4.x and a list of resource types. A token error here means a setup problem from the section above, not a code problem.

2. search_assets with no arguments, then list_logs with status: done.

3. Enable writes on a throwaway instance and try create_log with a quantity.

Parts most worth checking on a real server, because they follow documented behavior but were only exercised against the mock:

• boolean filters (archived is sent as 0/1),

• quantity value written as {"decimal": "..."},

• timestamp filters as epoch seconds, timestamp writes as ISO 8601,

• the token endpoint path (/oauth/token, overridable).

Development

.venv/bin/pip install -e ".[dev]"
.venv/bin/pytest

Tests use httpx.MockTransport, so no farmOS server is needed.

AI disclosure

This repository was developed with substantial use of AI:

• The code, tests and documentation were written by Claude (Claude Sonnet 5.5, Anthropic) in an interactive session with the maintainer, who directed the work. The design choices, API behavior and docs were drafted by the model from farmOS's public documentation.

• The farmOS behavior is based on documentation, not on a live server. The model had no access to a real farmOS instance, so request shapes (filters, quantity values, timestamps, the OAuth token endpoint) follow the published docs and have only been exercised against a mock written alongside the code. The mock encodes the same assumptions as the code, so passing tests do not prove the server matches real farmOS behavior.

• Human review is limited. The code has not had a full independent audit. Treat it as you would any unreviewed third-party code: read it before running it, especially before giving it credentials or write access.

• Security-relevant choices to check: this server sends your farmOS credentials to the configured URL, can create/modify/delete records when enabled, and is driven by an AI model that can make mistakes. Use a dedicated low-privilege farmOS account (farm_viewer or farm_worker), keep FARMOS_ALLOW_WRITES and FARMOS_ALLOW_DELETE off unless you need them, and keep backups.

Issues and pull requests that fix incorrect farmOS behavior are especially welcome. Please say in your PR if AI tools were used.

Not included

• Uploading files/images, geometry editing, and data streams.

• farmOS add-on modules with custom fields are reachable through query_records / create_record, but have no dedicated tools.

• Only the stdio transport. Remote/HTTP hosting would need mcp.run(transport="streamable-http") plus your own authentication in front.