# NCREIF Custom Query MCP > NCREIF Custom Query allows your AI client to run custom SQL-like queries against institutional real estate data. It pulls performance metrics, historical index returns (NPI), Cap Rates, and occupancy stats from major US indices like NPI and ODCE. Forget manual spreadsheet lookups; just ask your agent for the numbers you need. ## Overview - **Category:** real-estate - **Price:** Free - **Tags:** investment-data, sql-queries, property-index, financial-analysis, institutional-data, market-intelligence ## Description You're gonna let your AI client run custom SQL-like queries against institutional real estate data using the NCREIF Query Tool API. This server pulls performance metrics, historical index returns (NPI), Cap Rates, and occupancy stats from major U.S. indices like NPI and ODCE. You don't gotta manually look up spreadsheets; you just ask your agent for the numbers you need. When you use `execute_query`, you can pull any data point from NCREIF that fits your criteria. This means you control the formulas when calculating total returns, whether it's based on income or appreciation data. You also get to filter results deep down by geography, like limiting a query to specific regions or CBSA areas, or narrowing it by property class. For index analysis, `get_historical_npi` retrieves historical total return performance for the NPI index over time. This lets you track how the market performed across different periods and calculate returns based on those long-term data points. To get quick reads on standard metrics, you use `get_predefined_kpi`. That tool fetches standardized key metrics with a simple request, pulling numbers like Cap Rates and Occupancy percentages. You can target specific indices using this system; it handles both the NPI (Property Index) and the ODCE (Fund Index). If you need to crunch the actual mechanics of returns, `execute_query` lets you run custom queries to calculate total returns that combine appreciation figures with income data points. You can also pull specific performance metrics for a given property type or region by using detailed filtering clauses within this query function. The capabilities cover accessing historical index data specifically from NPI over set time ranges. Beyond the indices, `get_predefined_kpi` provides immediate access to standardized key indicators like Occupancy percentages and Cap Rates through a streamlined request process. You can use any of these tools together; for instance, you might first run an `execute_query` to pull raw income data for a specific CBSA area, then follow up with `get_predefined_kpi` to check the current occupancy percentage for that same region. The system supports analyzing multiple indices. You can target the NPI or the ODCE when requesting performance metrics. If you need to restrict your search results, you've got filters available for the property type and specific geographic areas within a given state or county. Every tool operates on institutional-grade data, ensuring that what your agent hands you is accurate real estate intelligence. You can ask `execute_query` to calculate complex total returns based on multiple income streams and appreciation inputs simultaneously. This query function doesn't just pull data; it runs calculations for you against the NCREIF dataset. When checking historical performance, `get_historical_npi` provides a time series of the NPI index's total return history. The process is direct: one tool does one thing. You use `get_predefined_kpi` when you need standard numbers—think Cap Rates or Occupancy percentages—without building a massive query. Meanwhile, `execute_query` handles everything else; it pulls the granular data points and runs custom logic against them. Whether you're looking at raw property performance for filtering by region or needing to compare NPI versus ODCE historical trends, your agent can handle it. ## Tools ### execute_query Run a custom query to pull any data point from NCREIF that fits your criteria. ### get_historical_npi Retrieves historical total return performance for the NPI index over time. ### get_predefined_kpi Fetches standardized key metrics, such as Cap Rates and Occupancy percentages, using a simple request. ## Prompt Examples **Prompt:** ``` Show NPI total returns for the last 4 quarters. ``` **Response:** ``` Executing NPI query... The total return for Q4 2025 was 1.2%, following 0.8% in Q3. Here is the historical breakdown... ``` ## Capabilities ### Calculate Total Returns Run custom queries to calculate total returns based on income and appreciation data. ### Access Historical Index Data Get NPI historical return data over specific time ranges. ### Retrieve Standard Metrics Fetch predefined key performance indicators, like Cap Rates and Occupancy percentages. ### Filter by Geography or Type Limit query results using specific filters for region, CBSA, or property class. ### Analyze Specific Indices Target data from the NPI (Property Index) or ODCE (Fund Index). ## Use Cases ### Q1 Market Checkup A portfolio manager needs to know the Q1 performance of office space versus industrial properties. They ask their agent: 'What were the total returns for office vs. industrial in Q1?' The agent uses `execute_query`, filtering by property type and time, giving a direct comparison. ### Modeling Volatility An analyst needs to assess how NPI performed during recessions. They instruct the agent: 'Show me the historical NPI returns for 2008 through 2012.' The agent uses `get_historical_npi`, providing a clear, data-backed timeline. ### Quick Due Diligence A researcher needs to quickly check the current market health of a specific metro area. They prompt: 'What is the average Cap Rate in the Dallas CBSA?' The agent immediately calls `get_predefined_kpi`, bypassing hours of dashboard navigation. ### Deep Dive Comparison Someone needs to compare both historical trends and current metrics. They ask: 'Compare Q4 2025 NPI returns with the current average Cap Rate.' The agent intelligently calls both `get_historical_npi` and `get_predefined_kpi`, synthesizing a full answer. ## Benefits - **Run custom analytics:** Instead of writing complex SQL, you just ask for 'total returns' or 'income appreciation.' The `execute_query` tool handles the logic. - **Track history instantly:** You get historical NPI performance without jumping through time-series dashboards. Just ask your agent to use `get_historical_npi` for a 4-quarter view. - **Get standard KPIs fast:** Need Cap Rates or Occupancy percentages? The `get_predefined_kpi` tool delivers these common metrics in one shot, saving clicks and time. - **Filter by specific market conditions:** You can force the query to look only at a certain region (CBSA) or property class using detailed filtering clauses within any tool. - **Build complex reports easily:** By chaining tools—first running `get_predefined_kpi` then refining with `execute_query`—you build complete financial narratives directly in your chat. ## How It Works The bottom line is you talk naturally to your agent, and it handles the complex API calls required for deep real estate analysis. 1. First, you subscribe to this server and enter your required credentials: your NCREIF Username and Password. 2. Second, you instruct your AI client—say, 'What were the total returns for Q4 2025?'—and the agent maps that request to the appropriate tool. 3. Third, the server executes the query against institutional data and sends back clean, structured results (like JSON) directly into your chat or code environment. ## Frequently Asked Questions **How do I use NCREIF Custom Query to calculate total returns?** You use the `execute_query` tool. You simply tell your agent what metrics you want to combine (like income and appreciation) and which time frame, letting the server handle the underlying calculation logic. **Can I check historical NPI returns using get_historical_npi?** Yes. The `get_historical_npi` tool fetches performance data for the NPI index over specific, defined periods (e.g., last 4 quarters), giving you a clear time-series breakdown. **What is the difference between get_predefined_kpi and execute_query?** The `get_predefined_kpi` tool handles common, standardized metrics (Cap Rates, Occupancy) with simple calls. Use `execute_query` when you need to build custom reports or combine multiple non-standard data points. **Do I need credentials for NCREIF Custom Query?** Yes. You must subscribe and provide your full NCREIF Username and Password so the agent can authenticate against the institutional data source. **When using `execute_query`, how do I apply specific filters, like by region or property type?** You filter results by including powerful 'WHERE' clauses directly in your query string. You specify the criteria—for example, filtering properties only within a certain CBSA code. This allows you to narrow down large datasets efficiently. **If I run `execute_query` and encounter an error, how should I troubleshoot it?** First, check your SQL-like syntax against the NCREIF documentation; most issues are simple typos or incorrect column names. If the syntax is correct, verify that the requested data index is accessible with your current credentials. **Does `get_historical_npi` provide returns for specialized indices, such as timberland or farmland?** The `get_historical_npi` tool focuses specifically on major US real estate indices. For highly specialized metrics like timberland performance, you should use the custom query feature with `execute_query`. **What is the ideal format for the input parameters when writing a complex query via `execute_query`?** The tool expects an SQL-like string that defines both your required metrics (e.g., 'income returns') and the necessary filtering conditions. Keep the language concise and highly specific to ensure accurate results. **Who can access this API?** Access is limited to NCREIF Data Contributor Members and paid Data Subscribers. You must use your website login credentials.