What is MCP?

MCP (Model Context Protocol) is a standard that allows AI assistants like Claude to interact with external tools and data sources. Our MCP Server enables Claude to query countries, states, cities, and postal codes directly in conversations.

Installation

Install globally via npm:

npm install -g @countrydataapi/mcp-server

Or use directly with npx (no installation required):

npx @countrydataapi/mcp-server

Configuration for Claude Desktop

Add the following to your Claude Desktop configuration file:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "country-data-api": {
      "command": "npx",
      "args": ["@countrydataapi/mcp-server"],
      "env": {
        "COUNTRY_DATA_API_KEY": "your-api-key-here"
      }
    }
  }
}

After saving the configuration, restart Claude Desktop.

Available Tools

Once configured, Claude will have access to the following tools:

Countries

Tool	Description
`get_countries_all`	Get all countries
`get_country_by_name`	Get country by name
`get_country_by_code`	Get country by ISO code (ES, ESP, 724)
`get_countries_by_region`	Get countries by region (Europe, Asia, etc.)
`get_countries_by_currency`	Get countries by currency (EUR, USD, etc.)
`get_countries_by_language`	Get countries by language (spa, eng, etc.)
`get_countries_by_timezone`	Get countries by timezone

States

Tool	Description
`get_states_all`	Get all states/provinces
`get_states_by_country`	Get states for a country
`get_states_by_city`	Get states containing a city

Cities

Tool	Description
`get_cities_all`	Get all cities
`get_city`	Get city by name
`get_cities_by_country`	Get cities for a country
`get_cities_by_state`	Get cities for a state

Zipcodes

Tool	Description
`get_zipcodes_by_country`	Get zipcodes for a country
`get_zipcodes_by_state`	Get zipcodes for a state

Select (Optimized - 1 token each)

Tool	Description
`get_select_countries`	Lightweight country list for dropdowns
`get_select_states`	Lightweight state list for dropdowns
`get_select_cities`	Lightweight city list for dropdowns

Status

Tool	Description
`get_api_status`	Get remaining API tokens

Example Conversations

Once configured, you can ask Claude things like:

Get Country Information

"What countries are in Europe?" "Tell me about Spain" "What's the capital of Germany?"

Find States/Provinces

"What states are in the United States?" "List the provinces of Canada"

City Queries

"What cities are in California?" "Find cities in the Madrid region"

Token Management

"How many API tokens do I have left?"

Common Parameters

Most tools accept these optional parameters:

Parameter	Description
`lang`	Response language: en, es, pt, fr, de, it
`fields`	Comma-separated list of fields to return
`limitToken`	Maximum tokens to use for this request

Environment Variables

Variable	Description	Required
`COUNTRY_DATA_API_KEY`	Your API key from countrydataapi.com	Yes

Troubleshooting

Claude doesn't see the tools

Make sure the configuration file is saved correctly
Restart Claude Desktop completely
Check that your API key is valid

Error: Invalid API key

Verify your API key is correct and has remaining tokens. You can check your token balance at your account dashboard.

Tools are slow

The MCP server uses the same API as direct requests. If queries are slow, try:

Using more specific queries (e.g., search by country instead of all)
Limiting results with limitToken
Using the select endpoints for dropdown data

Security Notes

Your API key is stored locally in the Claude Desktop configuration
The MCP server only communicates with the Country Data API
No data is sent to third parties

MCP Server for Claude