Skip to main content
Glama
tansuasici

country-state-city

by tansuasici
OverviewSchemaRelated ServersScoreDiscussions
TypeScript
Local

Country State City

About

Country State City provides 250+ countries, 5,000+ states, and 150,000+ cities as an NPM package, an MCP server for AI assistants, and an interactive web app — all ISO 3166-1 compliant.

Related MCP server: OpenStreetMap MCP Server

Features

  • 250+ Countries, 5K+ States, 150K+ Cities — ISO 3166-1 compliant

  • Multiple Formats — JSON, CSV, XML, YAML output

  • MCP Server — Connect to Claude Desktop and AI assistants

  • TypeScript — Full type definitions included

  • Dual Entry Points — Separate browser (ESM) and Node.js (CJS/ESM) builds

  • Search — Filter countries, states, and cities by name

  • Interactive Playground — Test the API at the live demo

Quick Start

npm install @tansuasici/country-state-city
import { CountryStateCity } from '@tansuasici/country-state-city';

const countries = CountryStateCity.getAllCountries();
const turkey = CountryStateCity.getCountryByIso2('TR');
const states = CountryStateCity.getStatesByCountryId(225);
const cities = CountryStateCity.getCitiesByStateId(2175);

// Search
const results = CountryStateCity.searchCountries('United');

// Different formats
const csv = CountryStateCity.getAllCountries('csv');
const xml = CountryStateCity.getStatesByCountryId(231, 'xml');
const yaml = CountryStateCity.getCitiesByStateId(1416, 'yaml');

MCP Integration

Use location data directly in Claude Desktop and other MCP-compatible AI assistants.

Add to your claude_desktop_config.json:

{
  "mcpServers": {
    "country-state-city": {
      "command": "npx",
      "args": ["@tansuasici/country-state-city", "mcp"]
    }
  }
}

11 Tools — search_countries, get_country, get_countries_by_region, get_states, search_states, get_cities, search_cities, get_stats, get_regions, get_timezones, get_currencies

5 Resources — ://countries, ://countries/{iso2}, ://countries/{iso2}/states, ://states/{id}/cities, ://stats

API Reference

Country Methods

CountryStateCity.getAllCountries(format?: 'json' | 'csv' | 'xml' | 'yaml');
CountryStateCity.getCountryById(id: number);
CountryStateCity.getCountryByIso2(iso2: string);
CountryStateCity.getCountryByIso3(iso3: string);
CountryStateCity.searchCountries(query: string);
CountryStateCity.getCountriesByRegion(region: string);
CountryStateCity.getCountriesBySubregion(subregion: string);

State Methods

CountryStateCity.getAllStates(format?: 'json' | 'csv' | 'xml' | 'yaml');
CountryStateCity.getStateById(id: number);
CountryStateCity.getStatesByCountryId(countryId: number, format?: string);
CountryStateCity.getStatesByCountryCode(countryCode: string, format?: string);
CountryStateCity.searchStates(query: string, countryId?: number);

City Methods

CountryStateCity.getAllCities(format?: 'json' | 'csv' | 'xml' | 'yaml');
CountryStateCity.getCityById(id: number);
CountryStateCity.getCitiesByStateId(stateId: number, format?: string);
CountryStateCity.getCitiesByCountryId(countryId: number, format?: string);
CountryStateCity.searchCities(query: string, stateId?: number, countryId?: number);

Utility Methods

CountryStateCity.getStats();
CountryStateCity.getAllRegions();
CountryStateCity.getAllSubregions();
CountryStateCity.getAllTimezones();
CountryStateCity.getAllCurrencies();
CountryStateCity.exportData(dataType, format, options?);

TypeScript

import {
  CountryStateCity,
  Country,
  State,
  City,
  DataFormat,
  FormatOptions,
} from '@tansuasici/country-state-city';

Development

# Install dependencies
npm install

# Start dev server
npm run dev

# Build NPM package
npm run build:lib

# Build MCP server
npm run build:mcp

# Run tests
npm test

Contributing

Contributions are welcome! Please read CONTRIBUTING.md for guidelines.

License

MIT — see LICENSE for details.

This server cannot be installed

A
license - permissive license
-
quality - not tested
B
maintenance

How are these scores calculated?

Maintenance

–Maintainers
–Response time
–Release cycle
1Releases (12mo)
Commit activity

Resources

Unclaimed servers have limited discoverability.

Looking for Admin?

If you are the server author, to access and configure the admin panel.

Latest Blog Posts

MCP directory API

We provide all the information about MCP servers via our MCP API.

curl -X GET 'https://glama.ai/api/mcp/v1/servers/tansuasici/CountryStateCity'

If you have feedback or need assistance with the MCP directory API, please join our Discord server