# USDA ERS MCP > The ERS USDA MCP connects your AI agent directly to the Agricultural Resource Management Survey (ARMS). Pull official, primary-source data on U.S. farm finances, production metrics, and resource use. It lets you query specific years, states, or variable definitions without downloading massive CSV files. ## Overview - **Category:** data-analytics - **Price:** Free - **Tags:** agriculture, economic-data, survey-data, farm-finance, public-records, data-retrieval ## Description This MCP gives you direct access to the USDA Economic Research Service's core database for American agriculture. Instead of navigating government websites and manually exporting data sets, your agent handles the heavy lifting. You can ask it to pull detailed financial records—like gross cash farm income or total expenses—for a specific year and region. It also lets you segment that data by farm type or operational category. Because this is official primary data, it's reliable. When you connect this MCP through Vinkius, your agent treats the USDA database like another internal tool, allowing you to integrate these crucial agricultural metrics right into your analysis workflow. You just describe what you need—say, 'the net cash farm income for commercial farms in Iowa in 2019'—and get a structured answer back. ## Tools ### get_arms_categories Lists the available primary and sub-categories used to classify farm operations in ARMS. ### get_arms_farmtypes Retrieves a complete list of official farm business types recognized by the survey data. ### get_arms_reports Finds all available reports and variables, helping you know what metrics are even measurable. ### get_arms_states Retrieves a list of all surveyed states and the associated metadata for regional analysis. ### get_arms_surveydata Pulls actual ARMS survey results, requiring you to specify the year and at least one report or variable. ### get_arms_variables Provides detailed metadata and definitions for every single variable used in the ARMS dataset so you know what the numbers mean. ### get_arms_years Lists all historical survey years available for longitudinal analysis of farm data. ## Prompt Examples **Prompt:** ``` Show me all available years for the ARMS survey data. ``` **Response:** ``` I've retrieved the available years for the ARMS dataset. Data is available for a wide range of years, including recent periods like 2021 and 2022. Which year would you like to analyze? ``` **Prompt:** ``` Get the income statement survey data for the year 2022. ``` **Response:** ``` Fetching the 2022 income statement data... I have retrieved the financial results. This includes metrics for gross cash farm income, total cash expenses, and net cash farm income across the surveyed regions. ``` **Prompt:** ``` List the different farm types available in the ERS ARMS dataset. ``` **Response:** ``` I've found the available farm types. Categories include 'operator households', 'commercial farms', and various other classifications based on production and economic size. ``` ## Capabilities ### Retrieve historical financial data Get detailed records on farm income and expenses for specific years and regions. ### Define geographic scope List all available U.S. states and regional metadata used in the survey reports. ### Segment farm types Filter results to focus only on specific operational structures, like operator households or commercial farms. ### Understand variable definitions Look up the precise definition and metadata for any economic metric used in the survey. ### Determine available metrics List all possible reports, variables, and categories contained within the ARMS dataset. ## Use Cases ### Comparing farm health over time A researcher needs to see how the total cash expenses changed for Iowa farms between 2015 and 2020. They tell their agent: 'Get me all available years first, then pull the expense data.' The agent uses `get_arms_years` and `get_arms_surveydata`, delivering a clean time-series report. ### Segmenting by operation type A consultant needs to analyze if large commercial farms behave differently than small operator households. They ask the agent to filter data using `get_arms_farmtypes` and then pull the required income metrics, isolating the two groups for comparison. ### Validating metric meanings An analyst receives a report that mentions 'gross cash farm income' but isn't sure of its exact definition. They run `get_arms_variables` and get the precise metadata, ensuring their model uses the correct calculation. ### Targeting specific regions A policy advisor only cares about data from the Midwest region. They start by running `get_arms_states`, confirming all relevant states are included before asking for the survey results to limit scope and clean up the output. ## Benefits - Access granular financial detail. Instead of general summaries, you pull specific metrics like 'net cash farm income' for the exact years and regions you need. - Pinpoint your data scope instantly. Use `get_arms_categories` or `get_arms_farmtypes` to narrow down results before pulling any numbers, saving time. - Maintain historical consistency. By using `get_arms_years`, you can easily compare trends across multiple decades without manual dataset management. - Know exactly what you're querying. If a metric name is unclear, running `get_arms_variables` provides the formal definition for that variable. - Build complex reports fast. Your agent coordinates between finding states (`get_arms_states`) and pulling data (`get_arms_surveydata`), automating multi-step analysis. ## How It Works The bottom line is you talk to it naturally; it translates that request into a precise data call and gives you clean results. 1. Subscribe to this MCP and provide your ERS USDA API Key in your agent's settings. 2. Tell your AI client what data you need, specifying the report, year, or region. For instance: 'I need the income statement for 2015.' 3. The MCP sends a structured query to the USDA database and returns the requested financial metrics directly to your agent. ## Frequently Asked Questions **How do I find out what metrics are available using get_arms_reports?** Running `get_arms_reports` lists all possible reports and variables, which is your first step. It tells you the specific names of the financial metrics you can request later. **Do I need to use get_arms_variables before get_arms_surveydata?** No, but it's smart practice. `get_arms_variables` lets you check the exact definition of a metric, confirming that the variable you are about to pull with `get_arms_surveydata` means what you think it means. **Can I get data for multiple states at once?** Yes. You first run `get_arms_states` to list all valid regions, then include that full list of states in your query when running `get_arms_surveydata`. **Which tool should I use to segment my data by farm structure?** Use `get_arms_farmtypes`. It gives you all the official classifications, and then you reference those types when pulling your final results with `get_arms_surveydata`. **What happens if I forget my USDA API Key when running get_arms_surveydata?** The agent will return an immediate authentication failure. You must supply a valid ERS API key in your client's credentials for the query to proceed. This prevents unauthorized access to protected data. **Should I use get_arms_years before attempting to retrieve survey results with get_arms_surveydata?** Yes, always run get_arms_years first. This confirms the precise time window available for your research. Knowing the current years prevents you from getting an error when querying data that hasn't been published yet. **How do I confirm the exact definitions and units of measure for a metric using get_arms_variables?** The tool provides detailed metadata for every ARMS variable. This documentation is crucial because it defines exactly what the raw numbers from the survey data represent, ensuring accurate interpretation. **Can get_arms_states tell me which variables are relevant to a specific region?** No, get_arms_states only provides state-level metadata. To understand the available metrics for those states, you must run get_arms_variables separately. You combine this information in your analysis. **What is required to fetch specific survey results using this server?** To use the `get_arms_surveydata` tool, you must provide at least one year and either a 'report' name (like income+statement) or a specific 'variable' ID (like igcfi). **Can I see which states are available in the ARMS dataset?** Yes! Use the `get_arms_states` tool to retrieve a list of all U.S. states covered by the survey along with their associated metadata. **How do I find the meaning of a specific variable code like 'igcfi'?** You can use the `get_arms_variables` tool to fetch detailed metadata and descriptions for all variables used in the Agricultural Resource Management Survey.