API Documentation - Endpoints & Examples

MCP Server for Claude

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

  1. Make sure the configuration file is saved correctly
  2. Restart Claude Desktop completely
  3. 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

Links