Documentación de la API - Endpoints y Ejemplos

MCP Server para Claude

¿Qué es MCP?

MCP (Model Context Protocol) es un estándar que permite a asistentes de IA como Claude interactuar con herramientas y fuentes de datos externas. Nuestro MCP Server permite a Claude consultar países, estados, ciudades y códigos postales directamente en las conversaciones.

Instalación

Instala globalmente via npm:

npm install -g @countrydataapi/mcp-server

O usa directamente con npx (sin instalación):

npx @countrydataapi/mcp-server

Configuración para Claude Desktop

Añade lo siguiente a tu archivo de configuración de Claude Desktop:

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": "tu-api-key-aqui"
      }
    }
  }
}

Después de guardar la configuración, reinicia Claude Desktop.

Herramientas Disponibles

Una vez configurado, Claude tendrá acceso a las siguientes herramientas:

Países

Herramienta Descripción
get_countries_all Obtener todos los países
get_country_by_name Obtener país por nombre
get_country_by_code Obtener país por código ISO (ES, ESP, 724)
get_countries_by_region Obtener países por región (Europe, Asia, etc.)
get_countries_by_currency Obtener países por moneda (EUR, USD, etc.)
get_countries_by_language Obtener países por idioma (spa, eng, etc.)
get_countries_by_timezone Obtener países por zona horaria

Estados/Provincias

Herramienta Descripción
get_states_all Obtener todos los estados/provincias
get_states_by_country Obtener estados de un país
get_states_by_city Obtener estados que contienen una ciudad

Ciudades

Herramienta Descripción
get_cities_all Obtener todas las ciudades
get_city Obtener ciudad por nombre
get_cities_by_country Obtener ciudades de un país
get_cities_by_state Obtener ciudades de un estado

Códigos Postales

Herramienta Descripción
get_zipcodes_by_country Obtener códigos postales de un país
get_zipcodes_by_state Obtener códigos postales de un estado

Select (Optimizado - 1 token cada uno)

Herramienta Descripción
get_select_countries Lista ligera de países para dropdowns
get_select_states Lista ligera de estados para dropdowns
get_select_cities Lista ligera de ciudades para dropdowns

Estado

Herramienta Descripción
get_api_status Obtener tokens restantes de la API

Ejemplos de Conversación

Una vez configurado, puedes preguntar a Claude cosas como:

Obtener Información de Países

"¿Qué países hay en Europa?" "Cuéntame sobre España" "¿Cuál es la capital de Alemania?"

Buscar Estados/Provincias

"¿Qué estados tiene Estados Unidos?" "Lista las provincias de Canadá"

Consultas de Ciudades

"¿Qué ciudades hay en California?" "Encuentra ciudades en la comunidad de Madrid"

Gestión de Tokens

"¿Cuántos tokens de API me quedan?"

Parámetros Comunes

La mayoría de herramientas aceptan estos parámetros opcionales:

Parámetro Descripción
lang Idioma de respuesta: en, es, pt, fr, de, it
fields Lista de campos a retornar separados por comas
limitToken Máximo de tokens a usar para esta petición

Variables de Entorno

Variable Descripción Requerida
COUNTRY_DATA_API_KEY Tu API key de countrydataapi.com Sí

Solución de Problemas

Claude no ve las herramientas

  1. Asegúrate de que el archivo de configuración está guardado correctamente
  2. Reinicia Claude Desktop completamente
  3. Verifica que tu API key es válida

Error: API key inválida

Verifica que tu API key es correcta y tiene tokens disponibles. Puedes comprobar tu saldo de tokens en el panel de tu cuenta.

Las herramientas son lentas

El servidor MCP usa la misma API que las peticiones directas. Si las consultas son lentas, prueba:

  • Usar consultas más específicas (ej. buscar por país en vez de todos)
  • Limitar resultados con limitToken
  • Usar los endpoints select para datos de dropdowns

Notas de Seguridad

  • Tu API key se almacena localmente en la configuración de Claude Desktop
  • El servidor MCP solo se comunica con la Country Data API
  • No se envían datos a terceros

Enlaces