This MCP server exposes access to the USDA NASS API (Quick Stats) via three primary tools:

• get_full_dataset(query): Retrieve all available data for a given commodity, location, and time. The query is a dictionary with keys 'commodity', 'location', and 'time', each containing parameter-value pairs. The result is returned as a string containing the full response text.
• get_db_record_count(query): Return the count of database records for a given commodity, location, and time. The query format mirrors get_full_dataset. The result is a JSON string with a single key 'count'.
• get_param_values(query): Retrieve all possible values for a specific query parameter by name. The query should include a 'param' key with the parameter name. The result is a JSON string listing the parameter values.

To use the server, ensure you have a valid NASS API key and configure the NASS_API_KEY environment variable. After starting, send requests to the MCP server endpoint (configured via NASS_MCP_HOST and NASS_MCP_PORT). The server processes requests and returns results in the specified formats (CSV/JSON/XML as configured by NASS_MCP_FORMAT).

Prerequisites:

• Python 3.8+ installed on your system
• pip available
• Optional: virtual environment tool (venv) or virtualenv

Step-by-step installation:

1. Clone the repository: git clone https://github.com/kin5/nass-mcp-server.git cd nass-mcp-server

2. Create and activate a virtual environment (recommended): python -m venv venv

   On macOS/Linux

   source venv/bin/activate

   On Windows

   venv\Scripts\activate.bat

3. Install dependencies: pip install -r requirements.txt

4. Configure environment variables:

   • Copy the example env file and edit it: cp .env.example .env

     Edit .env to set NASS_API_KEY and other settings

   • Ensure the API key is set in your environment (or via the .env loader in the app).

5. Run the MCP server: python -m nass

6. Optional: Docker-based setup (if provided in the repository): docker build -t nass-mcp-server . docker run -p 8000:8000 nass-mcp-server

Notes:

• The server uses the NASS API key to fetch data from the Quick Stats API. Ensure you have a valid key.
• If you prefer uv (Python package/virtual environment manager), install uv and follow the project-specific guidance to run the package. The sample command above uses Python directly for simplicity.

Environment variables and configuration tips:

• NASS_API_KEY: Your NASS API key required to access the Quick Stats API.
• NASS_MCP_HOST: Host address the MCP server will bind to (default 0.0.0.0).
• NASS_MCP_PORT: Port the MCP server will listen on (default 8000).
• NASS_MCP_FORMAT: Default data format returned by the NASS API (CSV, JSON, or XML).

Common issues:

• Invalid API key or exhausted quota may cause API request failures. Verify the key and rate limits.
• If the server fails to bind to a port, check for conflicts or firewall rules.
• If using a virtual environment, ensure it is activated when starting the server.

Configuration options:

• You can adjust the command-line transport if exposed by the server (not shown in this README). The MCP supports default environment-variable-driven configuration and can be extended to accept CLI options for host/port/format.