# Maranhão Open Data MCP > Maranhão Open Data connects your AI agent directly to the state's government transparency portal. It lets you discover, inspect metadata, and query public datasets from Maranhão, Brazil—all via structured commands like `search_packages` or complex SQL execution using `search_datastore_sql`. This is for anyone who needs reliable, real-time access to official public records. ## Overview - **Category:** knowledge-management - **Price:** Free - **Tags:** open-data, transparency, public-records, ckan, dataset-query, state-data ## Description Listen up. The Maranhão Open Data MCP Server hooks your AI agent straight into the state government's public transparency portal. Forget clicking through endless web forms or manually downloading zip files; you just talk to your agent, and it handles all the API calls needed to pull real-time data from Maranhão, Brazil. When you use this server, your agent interacts with structured tools, giving you deep analytical access without needing external scripts. It's built for anyone who needs reliable, official records right now. **Discovering What’s Available** If you don't know what data exists, you start by mapping the landscape. You can run `list_packages` to get a complete rundown of every single public dataset package hosted on that portal. Need something specific? Use `search_packages`—you just punch in a topic or keyword, and your agent filters through the massive catalog to show only relevant packages. This is how you narrow down what’s out there. **Inspecting Data Sources and Metadata** You've found a promising package, but you need to know exactly what it contains before you commit to querying it. You call `get_package` for detailed metadata on the whole dataset; this tells you about its overall scope and who owns it. If that package has multiple files or endpoints—maybe a CSV dump alongside an API feed—you use `get_resource` to inspect the specific structure of that particular file or endpoint, letting you know if it's ready for queries. **Searching Within DataTables** Once you have identified a resource, you can start pulling data. For basic filtering on existing rows within a table, your agent runs `search_datastore`. This is the quick and dirty way to filter records based on simple criteria—like finding all entries from a specific year or department. But what if that doesn't cut it? If you need complex analysis, like joining tables together or applying advanced filters across multiple columns (say, tracking every contract over $50,000 *and* filed in the last quarter), you gotta use `search_datastore_sql`. This function lets your agent run raw SQL queries directly against the data store. It handles deep analysis that simple filtering just can't touch. The whole process flows like this: first, you list packages to see everything; then, you search or filter using keywords via `search_packages`; next, you nail down the details of a package with `get_package` and check specific file structures with `get_resource`; finally, you either use `search_datastore` for simple pulls or hit it hard with raw SQL in `search_datastore_sql` to get exactly what you need. It's a complete data pipeline, built right into your agent. ## Tools ### get_package Retrieves the metadata for an entire dataset package, giving you details on its scope and contents. ### get_resource Fetches detailed metadata about a specific resource within a dataset (e.g., checking if it's a CSV file or API endpoint). ### list_packages Returns a complete list of every available public data package hosted on the portal. ### search_datastore_sql Runs complex SQL queries against the data store. This is used when you need to join tables or use advanced filters. ### search_datastore Executes basic searches for records within an existing resource in the DataStore, useful for simple filtering. ### search_packages Filters and searches for specific packages by topic, name, or keyword across all available datasets. ## Prompt Examples **Prompt:** ``` List all available datasets on the Maranhão Open Data portal. ``` **Response:** ``` I've retrieved the list of datasets. There are several packages available, including 'Receitas Estaduais', 'Despesas por Órgão', and 'Contratos Públicos'. Which one would you like to explore? ``` **Prompt:** ``` Search for datasets related to 'saúde' (health). ``` **Response:** ``` Searching for 'saúde'... I found datasets such as 'Leitos Hospitalares' and 'Vacinação COVID-19'. Do you want the metadata for any of these? ``` **Prompt:** ``` Run a SQL query to select the first 5 rows from the resource 'd3b0c...'. ``` **Response:** ``` Executing SQL query... Here are the first 5 records from the requested resource, showing columns for Date, Value, and Description. ``` ## Capabilities ### Discover available datasets The agent uses `list_packages` or `search_packages` to retrieve a list of all topics and packages available on the portal. ### Check dataset metadata You call `get_package` to get detailed information about an entire dataset package, including its scope and owners. ### Inspect specific data files The tool uses `get_resource` to retrieve the metadata for a particular file or API endpoint within a dataset. ### Search basic records in a table For quick filtering on existing rows, run `search_datastore` to query data based on simple criteria. ### Execute complex SQL queries You use `search_datastore_sql` to run raw SQL against the data store. This handles deep analysis that basic searching can't achieve. ## Use Cases ### Tracking public spending over time A researcher needs to see how state spending on education changed between 2018 and 2023. They don't want to download five separate CSV files. Instead, they prompt their agent: 'Run a query joining the Spending and Year tables for column X.' The agent uses `search_datastore_sql` to execute the complex join and returns a single, clean table. ### Verifying dataset availability A journalist wants to write about public health initiatives but isn't sure what data exists. They run 'List all packages related to medicine.' The agent uses `search_packages` and returns a list like 'Leitos Hospitalares' and 'Vacinação COVID-19', immediately showing the scope of available info. ### Checking for specific contract details A policy analyst wants to find all public contracts over $50,000 awarded in Q4. They use `search_datastore_sql` with a precise WHERE clause on the ContractValue column. This bypasses manual searching and pulls exactly the records they need for their report. ### Understanding data limitations A developer needs to know if a dataset contains both demographic data and API endpoints. They use `get_package` first, which returns all metadata. Then they call `get_resource` on the relevant resource ID to confirm it's not just a static PDF but an active endpoint. ## Benefits - Deep analysis happens when you use `search_datastore_sql`. This lets you run complex join queries on government tables, which is impossible with simple front-end searching. - You save time finding datasets. Instead of manually browsing the portal, running a search via `search_packages` filters hundreds of records down to the specific topic (like 'finance') you need. - The agent handles metadata checks for you. You don't have to guess if data is a PDF or a CSV; calling `get_resource` tells you exactly what format it is before you try to use it. - You get full transparency on the source. By using `list_packages`, you can quickly verify the scope of available records—from social indicators to public contracts—in one command. - It works across modalities. This server lets your agent handle structured data (via SQL) and unstructured metadata (via package/resource tools), all in the same chat session. ## How It Works The bottom line is: you get to treat government data like it's in a standard SQL database, without needing an intermediate API wrapper or manual web portal steps. 1. First, prompt your agent with what you need (e.g., 'Show me all health-related datasets'). The agent uses `search_packages` to narrow the scope. 2. Next, if you need specific data points, tell the agent to run an SQL query using `search_datastore_sql`, providing the necessary SELECT statement and table/resource name. 3. The system executes the call against the live Maranhão Open Data infrastructure. You get back a structured, paginated result set that your AI client can read immediately. ## Frequently Asked Questions **How do I find all available datasets on the Maranhão Open Data portal?** Use `list_packages`. This tool gives you a complete manifest of every dataset package hosted. If that list is too long, try running `search_packages` with keywords like 'education' or 'finance'. **Is `search_datastore_sql` the right way to query data?** Yes, `search_datastore_sql` is necessary for complex queries involving multiple tables (joins) or specific filtering criteria that simple searches cannot handle. It lets you write raw SQL. **What if I need metadata on a specific file?** You use `get_resource`. This tool takes the resource ID and checks its type—whether it's CSV, PDF, or an API endpoint—before you try to process it. **Can I check if a package exists before querying?** You can use `get_package`. This retrieves the full metadata for a dataset package. It's useful for verifying scope and ownership details before attempting a query. **What happens if I run many searches using `list_packages` or `search_datastore`?** You might hit rate limits, especially during large data pulls. The system recommends entering your Maranhão API Key to increase your allowed query volume and keep performance stable for intensive analysis. **How do I know what columns are available before using `search_datastore`?** You must use `get_package` first. This tool pulls the full metadata, which details all associated resources and lists their column names (the schema). You need that structure to write a successful query. **Besides CSV files, what other data types can I inspect using `get_resource`?** The server handles more than just flat files. `get_resource` retrieves metadata for various endpoints—this includes links to API documents and PDF records—so you know exactly how to access the original source material. **If I get an error when running a query with `search_datastore_sql`, what should I check?** First, verify your SQL syntax; that's the most common issue. Second, confirm column names and data types using `get_package` metadata before you execute complex queries. **How do I find datasets about a specific topic like 'education'?** You can use the `search_packages` tool with a query string. For example, searching for 'educação' will return all related datasets available on the portal. **Can I query the actual content of a CSV file without downloading it?** Yes! If the resource is in the DataStore, use `search_datastore` with the Resource ID to search through the rows directly. **Is it possible to perform complex filtering using SQL?** Absolutely. Use the `search_datastore_sql` tool to execute standard SQL queries against any resource stored in the portal's DataStore.