# CountryStateCity MCP

> CountryStateCity provides direct access to global geographical data, letting your AI agent query ISO codes and location metadata conversationally. Instantly list countries, find states within a region, or drill down to specific cities with latitude/longitude context.

## Overview
- **Category:** developer-tools
- **Price:** Free
- **Tags:** geographic-data, iso-codes, location-services, global-database, address-validation

## Description

Need to validate shipping addresses or build a database that requires accurate geopolitical boundaries? This MCP connects your AI client directly to comprehensive global location data. You can ask for everything from a full list of all countries and their codes, to listing every state within a country like India, or pulling specific cities inside a region like New York.

This means you don't have to copy-paste lookups or consult multiple API endpoints just to validate coordinates. Your agent handles the hierarchy automatically, giving you precise data points—like latitude and longitude for any address—right in your chat window. If you use Vinkius, this MCP fits right into your existing catalog of powerful tools, letting you query location facts alongside everything else you're building.

## Tools

### get_country
Gets detailed information, including codes, for one specific country.

### get_state
Retrieves details for a single administrative state or province.

### list_cities_by_country
Lists every city within an entire country (requires Supporter+ tier).

### list_cities_by_state
Lists all cities contained inside a specific state or province.

### list_countries
Retrieves a full list of every recognized country globally.

### list_states
Lists all states and provinces that belong to a given country.

## Prompt Examples

**Prompt:** 
```
List all countries and include their emojis.
```

**Response:** 
```
I've retrieved the list of countries. Here are a few: Afghanistan (AF) 🇦🇫, Albania (AL) 🇦🇱, Algeria (DZ) 🇩🇿, and Andorra (AD) 🇦🇩. Would you like the full list or details for a specific one?
```

**Prompt:** 
```
What are the states in India (IN)?
```

**Response:** 
```
Querying states for India... I found 36 states/territories, including Maharashtra (MH), Delhi (DL), Karnataka (KA), and Tamil Nadu (TN). Which state would you like to explore further?
```

**Prompt:** 
```
List the cities in the state of New York (NY), US.
```

**Response:** 
```
Fetching cities for New York, United States... I've found cities such as Albany, Buffalo, New York City, and Rochester. Do you need specific details for any of these cities?
```

## Capabilities

### Retrieve global country data
Get a comprehensive list of every country and its associated ISO codes, phone codes, and emojis.

### Discover regional states
List all administrative divisions or provinces that belong to a specific country you name.

### Identify cities by state
Fetch a list of every city located within a specific state's boundaries.

### Find all cities in a country
Generate a complete list of cities belonging to an entire nation.

## Use Cases

### Validating a new market's address structure
A logistics planner needs to know if all the states in Mexico are properly listed. They prompt their agent, and it runs `list_states` against Mexico, giving them a definitive list of administrative divisions they need for their internal database.

### Building an international form generator
A developer needs to create a country selector that also lists all subsequent states. They use the agent with `list_countries` first, then chain it with `list_states` for the selected region, ensuring the dropdowns are always current.

### Debugging location data discrepancies
A data analyst finds a city listed incorrectly. They use the agent to cross-reference using `get_state` and then check that specific location's details, confirming its correct state context before fixing the record.

### Populating a country directory
A content manager needs to write an article listing every major city in China. They ask the agent to use `list_cities_by_country`, getting hundreds of clean, structured names ready for publication.

## Benefits

- Instead of manually querying for state lists, you can ask the agent to use `list_states` and get all provinces for any country right away. This saves time in building out international forms.
- Build your application's backend logic around validated addresses. Use the tools like `get_country` or `get_state` to pull precise ISO codes needed for payment gateways or tax calculations.
- Need a comprehensive list of all cities across an entire nation? The MCP handles it using `list_cities_by_country`, giving you a full dataset without writing complex loops in your code.
- The agent allows you to drill down deep. If you know the state but not the country, you can use `get_state` and then specify which cities belong there via `list_cities_by_state`.
- It gives you foundational data points like latitude and longitude for any given location, making it perfect for mapping features or calculating shipping distances.

## How It Works

The bottom line is that your AI client acts as the middleman, translating your conversational request into precise database queries and handing back clean, structured location facts.

1. Subscribe to this MCP and enter your CountryStateCity API Key.
2. Connect the MCP to your preferred AI client (Claude, Cursor, etc.).
3. Ask a natural language question, like 'What are the states in Brazil?' or 'List all cities in California.' The agent uses the tools to get the specific data you asked for.

## Frequently Asked Questions

**How do I use list_countries with CountryStateCity?**
Run `list_countries` to get every country name and its ISO codes. This tool gives you the fundamental starting point for any location query.

**What does get_state do in CountryStateCity?**
The `get_state` tool lets you fetch specific details about one single administrative division, like its name and codes, after you know which country it belongs to.

**Can I use list_cities_by_country with CountryStateCity?**
Yes, `list_cities_by_country` retrieves a complete directory of all cities within one nation. Remember, this function requires the Supporter+ tier.

**How do I get coordinates using the MCP?**
The data returned from most queries includes latitude and longitude for precise location context, allowing you to map or calculate distances easily.

**Is there a tool to list all states in a country? (list_states)**
Yes, use `list_states`. This tool takes a specific country and returns every associated state/province name and code.

**How do I use list_cities_by_state to find locations?**
list_cities_by_state lists all cities within a specified state. You provide the name of the state and its country code, and the MCP returns a complete roster of every city in that administrative division.

**What do I need to use get_country for accurate data?**
You must subscribe to the MCP and input your CountryStateCity API Key. This authentication step ensures secure access when retrieving detailed country metadata, like ISO codes or phone prefixes.

**Does get_country provide more than just a list of names?**
Yes, it provides robust geographic context for the queried nation. Beyond basic identifiers, you get specific fields including latitude, longitude coordinates, and current currency information.

**How can I list all cities within a specific state or province?**
Use the `list_cities_by_state` tool by providing the Country ISO2 code (e.g., 'US') and the State ISO2 code (e.g., 'NY'). The agent will return a list of all cities registered in that region.

**Can I get detailed metadata like emojis and phone codes for a country?**
Yes! The `get_country` tool allows you to fetch full details for a specific country using its ISO2 code. You can also use `list_countries` with the `fields` parameter to include 'emoji' or 'phonecode' in the results.

**Is there a limit when listing all cities in a country?**
The `list_cities_by_country` tool requires a Supporter+ tier API key from CountryStateCity. For standard users, it is recommended to use `list_cities_by_state` to query cities in smaller administrative batches.