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: mireye-mcp

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

Resources

Prompts

Data sources and public accessibility

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

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.