CountryStateCity MCP. Resolve location hierarchies (Country $\rightarrow$ State $\rightarrow$ City)
Gemini Works with every AI agent you already use
…and any MCP-compatible client
Just plug in your AI agents and start using Vinkius.
CountryStateCity provides global geographic data access. It lets your AI agent look up country details, state/province lists, and specific cities using ISO codes and metadata.
Need to validate a shipping address or clean a database of locations? This server handles the hierarchy: listing countries, then states within a country, and finally cities within a state.
It gives you lat/long, currency, and full ISO codes instantly.
What your AI agents can do
Get country
Gets specific details and metadata for a single country.
Get state
Gets specific details and metadata for a single state or province.
List cities by country
Lists all cities within a specified country (Supporter+ tier required).
Retrieves specific metadata, codes, and details for a single, identified country.
Retrieves specific metadata, codes, and details for a single, identified state or province.
Returns a complete list of all supported countries, including their ISO codes and phone codes.
Fetches all administrative divisions (states/provinces) belonging to a specific country.
Retrieves a list of all cities associated with a specific state or province.
Retrieves a list of all cities contained within a specified country.
Ask AI about this MCP
Supported MCP Clients
Gemini Waiting for input…
CountryStateCity MCP Server: 6 Tools for Geographic Data
Use these tools to retrieve country, state, and city details. They allow your AI agent to traverse the location hierarchy using ISO codes and metadata.
019e5d0dget country
Gets specific details and metadata for a single country.
019e5d0dget state
Gets specific details and metadata for a single state or province.
019e5d0dlist cities by country
Lists all cities within a specified country (Supporter+ tier required).
019e5d0dlist cities by state
Lists all cities within a specified state (Supporter+ tier required).
019e5d0dlist countries
Returns a comprehensive list of all countries supported by the database.
019e5d0dlist states
Lists all states or provinces belonging to a specific country.
Choose How to Get Started
Build a custom MCP for your own tools, or connect a ready-made integration from our catalog.
Build Your Own
Turn any API into an MCP. Import a spec, define Agent Skills, or deploy with MCPFusion.
- Import from OpenAPI, Swagger, or YAML specs
- Create Agent Skills with progressive disclosure
- Deploy to edge with MCPFusion framework
- Built in DLP, auth, and compliance on every call
- Real time usage dashboard and cost metering
- Publish to catalog or keep private
Make Your AI Do More
Start with CountryStateCity, then connect any of our 4,700+ other servers whenever your AI needs more. One click, no limits.
- Use this MCP plus 4,700+ others, all in one place
- Add new capabilities to your AI anytime you want
- Every connection is secured and compliant automatically
- Track usage and costs across all your servers
- Works with Claude, ChatGPT, Cursor, and more
- New servers added to the catalog every week
What you can do with this MCP connector
This server gives your AI agent global geographic data access. You can look up country details, state/province lists, and specific cities using ISO codes and other metadata. Need to validate a shipping address or clean up a database of locations? It handles the whole location hierarchy: listing countries, then states within a country, and finally cities within a state.
You get lat/long, currency, and full ISO codes instantly.
list_countries returns a complete list of all supported countries, giving you their ISO codes and phone codes.
get_country retrieves specific metadata, codes, and details for a single, identified country.
list_states fetches all administrative divisions (states or provinces) belonging to a specific country.
get_state retrieves specific metadata, codes, and details for a single, identified state or province.
list_cities_by_country lists all cities within a specified country (Supporter+ tier required).
list_cities_by_state lists all cities within a specified state (Supporter+ tier required).
How CountryStateCity MCP Works
- 1 Subscribe to the CountryStateCity server and enter your API key.
- 2 Your AI client calls the initial tool (e.g.,
list_countries) to establish the high-level scope. - 3 The agent uses the output data (e.g., a country ID) to call the next tool (e.g.,
list_states), completing the location lookup.
The bottom line is, you don't manage the API calls; your AI agent handles the multi-step process of traversing the location hierarchy for you.
Who Is CountryStateCity MCP For?
This is for developers and data analysts who deal with location data. If your job involves validating addresses, cleaning datasets, or building applications that need precise geographic context (like shipping or regional targeting), this is necessary. It stops you from having to write complex, multi-stage API calls just to find a country's coordinates.
Validates large spreadsheets of location data, checking if state IDs match known country hierarchies and filling in missing ISO codes.
Builds shipping logic that verifies if a given city-state combination is valid for a specific country before accepting an order.
Writes location lookups that need to chain together multiple API calls (Country $\rightarrow$ State $\rightarrow$ City) without writing brittle, nested code.
What Changes When You Connect
- Accurately map coordinates and metadata. Instead of guessing, you get specific latitude, longitude, and currency details for any location via
get_countryorget_state. - Validate location chains in one go. You can verify if a city belongs to a state, and if that state belongs to a country, using the
list_statesandlist_cities_by_statetools. - Build comprehensive country lists. Use
list_countriesto get every country's ISO2/ISO3 codes and phone codes without writing complex lookup queries. - Streamline data validation. When cleaning location records, use
list_cities_by_countryorlist_cities_by_stateto ensure the city actually exists in the target region. - Simplify complex lookups. The server manages the multi-step logic. You simply ask your agent for the location, and it handles the calls to
list_countries$\rightarrow$list_states$\rightarrow$list_cities_by_state. - Improve code reliability. By using dedicated tools, you remove the risk of writing complex, brittle SQL or multi-API calls that fail when data structures change.
Real-World Use Cases
Validating a new e-commerce shipping zone
A logistics developer needs to know if a user-provided address is valid for shipping. They ask their agent to run list_states for the country, then check list_cities_by_state using the returned state list. The agent quickly validates the full address chain, preventing failed shipments.
Cleaning a legacy database dump
A data analyst receives a database dump with location IDs and needs to fill in the missing ISO codes, phone codes, and full names. They use list_countries to get the master list and then use get_country for bulk metadata lookup, ensuring data integrity before migration.
Building a geo-aware content site
A content team wants to display accurate currency and time zone data for articles. They use the get_country tool to pull specific metadata for the target country, ensuring the site shows the correct local context.
Finding all regional divisions for a country
A researcher needs to map out all the administrative regions of a country. Instead of manually querying a dozen endpoints, they call list_states with the country name. The agent returns a complete list of states and provinces.
The Tradeoffs
Hardcoding location IDs
Writing code that assumes 'France' is always ID 12, or that 'California' is always state ID 4. This breaks every time the data changes or the database schema shifts.
→
Always use the server. First, call list_countries to get the correct Country ID, and then use list_states with that ID to find the State ID. This approach is dynamic and handles schema changes.
Running a monolithic SQL JOIN
Attempting to write a single, massive SQL query that joins the Country, State, and City tables to get all data. This often times out or fails due to memory limits on large datasets.
→
Use the server's tools. The AI client handles the join logic for you. Call list_countries first, then use list_states on the result, and finally list_cities_by_state to build the location context piece by piece.
Ignoring required tier access
Trying to list all cities using only the country name, assuming the data is public. The system fails because the list_cities_by_country tool requires the Supporter+ tier.
→
Check the tool documentation. You must use the appropriate tool (list_cities_by_country) and ensure your subscription level supports the required granularity.
When It Fits, When It Doesn't
Use this server if your primary need is validating or retrieving structured geographic data in a hierarchical manner (Country $\rightarrow$ State $\rightarrow$ City). You need to know if a location is valid, not just what the name is. For example, if you need the latitude and longitude for a known location, use get_country. Use this server if your data validation process relies on knowing the relationship between administrative divisions. Don't use this server if you only need a simple, single-field list (e.g., just a list of country names without codes). In that case, a simple database read or a basic list tool might suffice. If you need to check if a city exists in a state, the list_cities_by_state tool is the explicit mechanism you need.
Independent Platform Disclaimer: Vinkius is an independent platform and is not affiliated with, endorsed by, sponsored by, verified by, or otherwise authorized by CountryStateCity. All third-party trademarks, logos, and brand names are the property of their respective owners. Their use on this website is strictly for informational purposes to identify service compatibility and interoperability.
VINKIUS INFRASTRUCTURE
Cloud Hosted
Managed infra
V8 Isolated
Sandboxed per request
Zero-Trust Proxy
No stored credentials
DLP Enforced
Policy on every call
GDPR Compliant
EU data residency
Token Compression
~60% cost reduction
Works with Claude, ChatGPT, Cursor, and more
The Model Context Protocol standardizes how applications expose capabilities to LLMs. Instead of operating in isolation, your AI gains direct access to external platforms, live data, and real-world actions through secure, standardized connections.
This server provides 6 capabilities that interface natively with Claude, ChatGPT, Cursor, and any MCP client. No middleware. No custom integration required.
Available Capabilities
Dealing with location data means dealing with endless, nested lookup failures.
Before this, finding a complete address profile meant bouncing between three different databases: one for countries, one for states, and a third for cities. You’d write a chain of API calls, passing IDs manually, and if any single ID was missing or misspelled, the whole process broke. It was tedious, and you spent more time debugging the lookup chain than actually working with the data.
Now, you connect CountryStateCity. You just tell your agent the target location, and it runs the sequence. It handles the Country $\rightarrow$ State $\rightarrow$ City progression. You get structured, verifiable location data—latitude, longitude, and all the necessary ISO codes—in a single, conversational output.
CountryStateCity MCP Server: Get verifiable location context.
No more manual checks. You don't have to write code to validate if a city exists in a state, or if that state exists in a country. The `list_states` tool and `list_cities_by_state` tool handle the validation logic internally.
The server exposes the complex relationships so you don't have to. It gives you the full geographic context—the verifiable links between countries, states, and cities—in a single, reliable call. That's the difference.
Common Questions About CountryStateCity MCP
How do I use the CountryStateCity tool to find a city's coordinates? +
Use the get_country tool first to get the country's general context, then use list_cities_by_state (Supporter+ tier) to get the specific city, which will include the coordinates.
What is the difference between `list_states` and `list_countries`? +
list_countries gives you a global list of all countries. list_states requires you to provide a Country ID first; it then returns all the states or provinces for that specific country.
Do I need to call a specific tool for every piece of data? +
No. While the tools define the data points (e.g., get_state), your agent manages the sequence. You tell it what you want, and it determines which tools to call to get the complete answer.
Can I find all cities in a country using the CountryStateCity tool? +
Yes, use the list_cities_by_country tool. Keep in mind that this specific tool requires a Supporter+ tier subscription to function.
When should I use the `get_country` tool to find basic country information? +
Use get_country when you know the country name or ISO code and only need basic details. This is faster than listing all countries, especially if you just need the phone code or ISO3 code.
What happens if I use `list_cities_by_country` for a non-existent country? +
The tool returns a specific error message indicating the country does not exist. Your AI client can then prompt you for the correct country name or code.
Can the CountryStateCity server handle location data for non-English regions? +
Yes, the server supports multiple language inputs for location names. You can query for states or cities using names from various global languages.
Do I need to manually manage API keys when using the CountryStateCity tools? +
No, Vinkius manages the API key process for you. You simply connect your AI client, and the server handles the authentication in the background.
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.
Use it with your favorite AI tools
Connect this server to Cursor, Claude, VS Code, and more.
More in this category
Context7
Empower AI agents via Context7 — pull up-to-date documentation and code examples for any library or framework directly into your workspace.
Bitbucket
Manage your Git repositories via Bitbucket — list pull requests, commits, and pipelines directly from any AI agent.
Clerk
Add production-ready authentication to your app with user management, SSO, multi-factor auth, and session handling out of the box.
You might also like
Steam Platform & Hype Intelligence
The definitive server for Steam platform insights — track trending games, player counts, and social connections via AI.
Headscale (Tailscale Alternative)
Manage your private Tailscale network via Headscale — control users, nodes, and pre-auth keys directly from your AI agent.
Pipedrive Deals
Deep deal management — search, create, update, delete deals with pipeline tracking, timeline analysis, and participant management.