Skip to main content
Glama

cart-mcp

This MCP server computes soil resource concern ratings for an area of interest (AOI) using the same SQL pipeline CART (Nemecek, J. & Peaslee, S., USDA NRCS) uses against the public USDA Soil Data Access (SDA) web service, and exposes the results as MCP tools, resources, and prompts for AI-assisted conservation planning.

What this is not: an official NRCS/CART ranking engine. CART's full ranking score combines five components (Vulnerability, Planned Practice Effects, Resource Priorities, Program Priorities, Cost Efficiency). This server computes only the soil-condition ratings (the vulnerability input) from published SSURGO soil data. Official program determinations come from your NRCS field office.

Install

Requires Python >= 3.12 and uv. If uv is not installed yet:

# macOS / Linux
curl -LsSf https://astral.sh/uv/install.sh | sh
# Windows (PowerShell)
# irm https://astral.sh/uv/install.ps1 | iex

Then install the dependencies (uv auto-downloads a managed Python >= 3.12 if the system interpreter is older):

uv --version   # sanity check
uv sync

Related MCP server: Smart Irrigation MCP Server

Run

uv run cart-mcp                 # stdio transport (default, for MCP clients)
uv run cart-mcp --transport streamable-http --port 8000   # Streamable HTTP (recommended for remote/HTTP clients)
uv run cart-mcp --transport sse --port 8000               # legacy HTTP+SSE transport

Or during development:

uv run python -m cart_mcp

Verify the install

Confirm the server boots and exposes its tools (no network needed):

uv run python -c "import asyncio; from cart_mcp.server import mcp; [asyncio.run(mcp._list_tools(None)), print('ok')]"

Plain uv run cart-mcp (stdio) stays running by design, waiting for MCP traffic from the client; a quiet, non-exiting process is healthy. GUI users can instead attach the MCP Inspector to verify the server interactively.

Client configuration

Add to your MCP client config (opencode, Claude Desktop, etc.). The config assumes uv sync has been run in the repo checkout:

{
  "mcpServers": {
    "cart": {
      "command": "uv",
      "args": ["--directory", "/path/to/cart-assistant", "run", "cart-mcp"]
    }
  }
}

If the client reports uv: command not found (GUI clients on macOS/Linux often do not inherit the shell PATH where uv was installed), replace "command": "uv" with the absolute path from which uv (where uv on Windows).

opencode users can preconfigure both servers in a root opencode.json; all other clients use examples/mcp_config.json as a template.

See docs/usage.md for the user guide: framing an AOI, the token-efficient rating workflow, reading output, soil/risk maps, QGIS orchestration, benchmarking, and troubleshooting.

Tools

Tool

Description

rate_aoi

Rate an AOI (WKT, EPSG:4326) for resource concerns via the SDA web service. Accepts an optional concerns subset. Returns ratings with survey-data dates.

rate_aois

Rate multiple landunits in one pipeline run (aois = [{landunit, wkt}]); ideal for comparing fields/parcels. Invalid WKTs are reported per-landunit in errors without sinking the others.

get_aoi_soil_summary

Map units, components, and acreage intersecting an AOI (lightweight, no rating computation).

get_aoi_soil_map

Soil map as GeoJSON: AOI-clipped soil polygons with map unit properties (musym, muname, acres). Render directly with Leaflet/ArcGIS. Feature-count/byte caps bound the payload; truncated/dropped_features report omissions.

get_aoi_risk_map

Risk map as GeoJSON for one cointerp-backed concern: soil polygons carrying the dominant component's rating class/value; Order 5 units rated 'Not rated'. Feature-count/byte caps bound the payload; truncated/dropped_features report omissions.

list_concerns

All CART resource concerns with pipeline type, data source, and whether rating is computable in this server.

get_concern_details

Profile for one concern. summary=True returns a compact profile (rating classes, top-3 practices); summary=False returns the full profile (practices, regulatory crosswalk, interpretation).

get_rating_domain

Ordered rating classes (best→worst) for a concern.

list_practices_for_concern

NRCS conservation practices typically addressing a concern (advisory, from public NRCS practice-points materials).

validate_pipeline

Re-run the pipeline against the known T9981 Fld3/Fld4 test AOIs and diff against embedded golden values. Requires network.

Resources

URI

Description

cart://disclaimer

Advisory disclaimer for ratings

cart://concerns

Index of all concerns

cart://concerns/{key}

One concern's full profile

cart://domains/{concern}

Rating domain for a concern

cart://interpretations

Soil interpretation name mappings

Prompts

Prompt

Description

rate-land-for-conservation

Guided AI workflow: describe AOI, pick concerns, run rate_aoi, summarize ratings for a landowner.

validate-cart-pipeline

Run validate_pipeline and interpret results against golden values.

Data sources and public accessibility

All data used at runtime is public — no API keys, no credentials, no internal endpoints.

Input

Source

Access

Public-domain status

Soil ratings (cointerp), interpretation metadata (sdvattribute, distinterpmd), map units, components, horizons

USDA NRCS SSURGO published snapshots via the Soil Data Access web service (https://sdmdataaccess.nrcs.usda.gov/tabular/post.rest)

Anonymous, no auth

Federal government work (17 U.S.C. § 105)

data/concerns.json, rating_domains.json, interpretations.json, practice_links.json, concern_regulatory_map.json

Derived from public NRCS CART documentation and chapters

Embedded in package

Derived from federal works

data/test_aois.json, expected_outputs/*.csv

Public CART documentation test fields (T9981 Fld3/Fld4)

Embedded in package

Derived from federal works

Notes:

  • The SDA web service is a free public federal service without an SLA; the server makes one submission per rate_aoi call. Query.aspx (SOAP) is the documented fallback if the post.rest endpoint ever changes.

  • Ratings are only as fresh as each survey area's last publication (saverest); the server returns these dates with every rating.

  • Embedded data derives only from USDA NRCS federal publications; no third-party documents (e.g., journal articles) are redistributed.

  • SDA request constraints (100k row cap, timeout/memory failure modes) are enforced by the server's request caps (landunits, AOI area, timeout).

  • CART SQL queries, rating methodology, and domain tables are documented in the public CART reference repository: https://github.com/jneme910/CART (Nemecek, J. and Peaslee, S., USDA NRCS).

Development

uv run pytest                # offline tests (default)
uv run pytest -m network     # opt-in tests requiring live SDA access
uv run pytest -m bench       # opt-in benchmark: cart-mcp driven by a local LLM

License

MIT for the server code; embedded data is derived from public-domain US federal government works. See LICENSE.

Available Tools

10 tools
get_aoi_risk_mapA

Risk map for one cointerp-backed concern as GeoJSON (FeatureCollection).

Each feature is a soil polygon clipped to the AOI carrying the rating (rating_value, rating_class) of the dominant major soil component in its map unit. Order 5 survey map units are rated 'Not rated'. Supports cointerp-backed concerns only (e.g. the five SOH concerns, Hydric, Ponding/Flooding, AWS, Depth to Water Table, Drainage Class); SOC and other custom concerns raise an error.

Inputs: wkt (required), concern (required), landunit. Returns: object

get_aoi_soil_mapA

Soil map for an AOI as GeoJSON (FeatureCollection).

Each feature is a soil polygon clipped to the AOI with properties {landunit, mukey, musym, muname, invesintens, farmlndcl, poly_acres}. Render directly with Leaflet/ArcGIS; no ratings are computed.

Inputs: wkt (required), landunit. Returns: object

get_aoi_soil_summaryA

Map units and major components intersecting an AOI (no ratings).

Returns per map unit: mukey, symbol/name, survey order (invesintens), farmland class, acres, and its major components (compname, comppct_r, drainage class). Useful for transparency (E4) and leaching/water-table screening (W4).

Inputs: wkt (required), landunit. Returns: object

get_concern_detailsC

Full profile for one concern: domain, practices, regulatory references.

Inputs: concern (required). Returns: object

get_rating_domainB

Ordered rating classes (worst to best) for a concern.

Inputs: concern (required). Returns: object

list_concernsA

All CART resource concerns with pipeline type, data source, computability, and docs.

Inputs: no named parameters. Returns: object

list_practices_for_concernA

NRCS conservation practices that address a concern (advisory).

Sourced from the public NRCS CART Practice Points spreadsheet ('Assoc Ag Land' points). Practices are listed by NRCS practice code, name, and points - they are suggestions for discussion, not a formal practice plan.

Inputs: concern (required). Returns: object

rate_aoiA

Rate an area of interest (WKT, EPSG:4326) for CART soil resource concerns.

Submits the CART pipeline to the public Soil Data Access web service and returns the landunit rating for every ratable concern (or the subset given in concerns). Each rating includes rating_name, rating_value, rating_class and the survey-area publication date (soils_metadata). Results are advisory - not official NRCS scores.

Inputs: wkt (required), concerns, landunit. Returns: object

rate_aoisA

Rate multiple landunits in one pipeline run.

aois is a list of {"landunit": str (<=20 chars), "wkt": str (EPSG:4326)}. Ideal for comparing fields/parcels (e.g., EQIP/CSP portal parcel exploration).

Inputs: aois (required), concerns. Returns: object

validate_pipelineA

Re-run the pipeline on the T9981 Fld3/Fld4 test fields and diff against golden values.

Network required. Golden values are tied to the 2018 ND001/SD105 survey-area snapshots; a mismatch may be legitimate if those areas were republished since.

Inputs: no named parameters. Returns: object

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A3.8/5.0

    Scored across 10 tools

    Disambiguation4/5

    The tools are largely distinct, but rate_aoi and rate_aois are essentially the same operation for one vs. multiple areas, and get_concern_details includes rating domain information that overlaps with get_rating_domain. Still, the descriptions make the intended use clear.

    Naming Consistency5/5

    All tool names follow a consistent verb_noun pattern with clear prefixes (list_, get_, rate_, validate_). Pluralization and compound nouns are used predictably.

    Tool Count5/5

    With 10 tools, the set is well-scoped for the CART/AOI analysis domain. Each tool serves a clear purpose without redundancy.

    Completeness4/5

    The server covers listing concerns, retrieving details and ratings, generating soil and risk maps, and validating the pipeline. A minor gap is that risk maps only support cointerp-backed concerns, but rate_aoi covers custom concerns, so the overall workflow is complete.

    Maintenance

    ActivityInactive
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      A
      quality
      C
      maintenance
      Exposes Mireye Earth's geospatial data API as MCP tools (mireye_ask and mireye_fetch) for querying location-based information like elevation, flood zones, and wildfire risk for US places.
      2
      2
      MIT
    • A
      license
      Not graded
      quality
      D
      maintenance
      Exposes real-time soil sensor metrics as MCP Resources and irrigation valve controls as MCP Tools, enabling AI-driven agronomic decisions with built-in safety guardrails.
      Apache 2.0
    • A
      license
      Not graded
      quality
      D
      maintenance
      Enables AI assistants to perform geospatial analysis, spatial data processing, vector and raster operations, coordinate transformations, spatial statistics, mapping, and access to climate, satellite, and other geospatial data through MCP-compatible clients.
      MIT