This MCP server exposes ApogeoAPI's geographic data, currency, and IP geolocation endpoints as read-only tools that AI assistants can call directly.
Summary: Query country, state, city, live USD exchange rate, and IP geolocation data from Claude Desktop, Cursor, or any MCP client.
get_country — full country data by ISO2/ISO3 code (name, capital, region, population, currency, USD rate, timezones, phone code), with basic/standard/full detail levels
list_countries — paginated list of all countries
search_countries — find countries by partial name
get_states — list states/provinces for a country
get_cities — list cities for a numeric state ID
get_currency_rate — live USD exchange rate for a country's currency (refreshed every 4 hours)
geolocate_ip — country, region, city, coordinates, timezone, and EU membership for any IPv4/IPv6 address
global_search — search countries, states, and cities in one query
All tools are read-only with safe annotations, so clients run them without confirmation prompts. Requires an APOGEOAPI_KEY (free tier covers country/state tools plus a 14-day full-access trial; paid plans unlock cities, rates, geolocation, and global search). Note: the server schema labels get_states, get_cities, get_currency_rate, and geolocate_ip as "Starter plan or above," while the README lists states as Free and the others as Basic+ — worth verifying against the live API.
MCP (Model Context Protocol) server for ApogeoAPI — geographic data, live exchange rates, and IP geolocation for Claude Desktop, Cursor, and any MCP-compatible AI assistant.
This server exposes ApogeoAPI's REST endpoints as tools that AI assistants can call directly. Ask Claude "What is the current USD rate for Argentina?" or "Geolocate IP 8.8.8.8" and it will call the right tool automatically.
Related MCP server: Geodb Cities MCP Server
Tool | Description | Plan required |
| Full country data by ISO2/ISO3 code — name, capital, region, population, currency, timezones, phone code (plus the live USD rate on Basic+) | Free |
| Paginated list of all 250+ countries | Free |
| Search countries by partial name | Free |
| All states/provinces for a country | Free |
| All cities for a state by numeric state ID | Basic+ |
| Live USD exchange rate for a country's currency (updated every 4 hours) | Basic+ |
| Country, region, city, coordinates, timezone, and EU membership for any IPv4/IPv6 | Basic+ |
| Search across countries, states, and cities in one query | Basic+ |
Every new account gets 14 days of full access to the Basic+ tools, no credit card required.
All tools are read-only and declare the MCP tool annotations (readOnlyHint, destructiveHint, idempotentHint, openWorldHint), so clients can run them without a confirmation prompt.
Add the following to your claude_desktop_config.json:
macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
Windows: %APPDATA%\Claude\claude_desktop_config.json
{
"mcpServers": {
"apogeoapi": {
"command": "npx",
"args": ["-y", "@apogeoapi/mcp"],
"env": {
"APOGEOAPI_KEY": "apogeoapi_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
}
}
}
}Restart Claude Desktop after saving the file. The ApogeoAPI tools will appear in Claude's tool list.
Add the same block under mcpServers in Cursor's MCP configuration file (~/.cursor/mcp.json).
git clone https://github.com/APOGEOAPI/apogeoapi-mcp.git
cd apogeoapi-mcp
npm install
npm run buildThen reference the built file directly:
{
"mcpServers": {
"apogeoapi": {
"command": "node",
"args": ["/absolute/path/to/mcp-server/dist/index.js"],
"env": {
"APOGEOAPI_KEY": "apogeoapi_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
}
}
}
}Create a free account at app.apogeoapi.com
Go to API Keys and generate a new key
Paste the key into the APOGEOAPI_KEY environment variable above
No credit card required for the Free plan (1,000 req/month). New accounts get 14 days of full access.
Feature | Free | Basic ($19/mo) | Starter ($29/mo) | Professional ($79/mo) |
Countries (list, search, get) | Yes | Yes | Yes | Yes |
States & provinces | Yes | Yes | Yes | Yes |
Cities | 14-day trial | Yes | Yes | Yes |
Global search | 14-day trial | Yes | Yes | Yes |
Live currency rates | 14-day trial | Yes | Yes | Yes |
IP geolocation | 14-day trial | Yes | Yes | Yes |
Monthly requests | 1,000 | 15,000 | 100,000 | 500,000 |
Upgrade at app.apogeoapi.com/dashboard/billing.
Variable | Required | Description |
| Yes | Your API key from the dashboard |
| No | Override the API base URL (default: |
npm test builds the server, starts it over stdio with a real MCP client and calls every tool against the live API. It needs a key with access to every tool (Basic+ or an account in its 14-day trial):
APOGEOAPI_KEY=your_key npm testMIT
Geolocate an IPv4 or IPv6 address — returns country, region, city, coordinates, timezone, and EU membership. Requires Starter plan or above.
Inputs: address (required).
Get all cities for a state/province by state ID. Requires Starter plan or above.
Inputs: state_id (required), page, limit, fields.
Get full data for a country by ISO2 or ISO3 code — includes name, capital, region, population, currency, live USD exchange rate, timezones, and phone code.
Inputs: code (required), fields.
Get the live USD exchange rate for a country's currency. Updated every 4 hours. Requires Starter plan or above.
Inputs: country_code (required).
Get all states/provinces for a country. Requires Starter plan or above.
Inputs: country_code (required), page, limit, fields.
Search across countries, states, and cities in a single query. Returns the best matches from all geographic entity types.
Inputs: q (required), limit.
List all countries with pagination. Returns basic info by default — add fields=full for all data.
Inputs: page, limit, fields.
Search countries by name (e.g. "arg" finds Argentina). Returns paginated matches.
Inputs: q (required), page, limit.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
Scored across 8 tools
Each tool has a clearly distinct purpose with no overlap: geolocate_ip handles IP addresses, get_cities and get_states retrieve subnational divisions, get_country and search_countries focus on country data, get_currency_rate provides exchange rates, list_countries enumerates all countries, and global_search offers cross-entity search. The descriptions reinforce these boundaries, making tool selection unambiguous.
All tools follow a consistent verb_noun naming pattern with snake_case throughout: geolocate_ip, get_cities, get_country, get_currency_rate, get_states, global_search, list_countries, and search_countries. The verbs (geolocate, get, global_search, list, search) are well-chosen and predictable, creating a cohesive and readable set.
With 8 tools, the count is well-scoped for a geographic/geolocation API server. Each tool serves a specific and necessary function, such as retrieving countries, states, cities, currency rates, or performing searches, without redundancy. This number allows comprehensive coverage without being overwhelming.
The tool set provides complete coverage for geographic data retrieval: it includes CRUD-like operations for countries (list, get, search), subnational divisions (states and cities), IP geolocation, currency rates, and a global search. There are no obvious gaps, as all major geographic entities and related data are accessible, enabling agents to handle diverse queries effectively.
140+ data APIs for agents: finance, banking validation, geo, weather, text. One API key.
Weather, geocoding, FX rates, holidays, time zones, countries, earthquakes, sun and moon.
Weather, geocoding, FX rates, holidays, time zones, countries, earthquakes, sun and moon.
IP Geolocation: This API provides fast, reliable, and developer-friendly IP geolocation, ASN.
