@apogeoapi/mcp 1.0.0

package/README.md

@@ -0,0 +1,106 @@
+# @apogeoapi/mcp
+
+MCP (Model Context Protocol) server for [ApogeoAPI](https://app.apogeoapi.com) — geographic data, live exchange rates, and IP geolocation for Claude Desktop, Cursor, and any MCP-compatible AI assistant.
+
+## What it does
+
+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.
+
+## Available tools
+
+| Tool | Description | Plan required |
+|------|-------------|---------------|
+| `get_country` | Full country data by ISO2/ISO3 code — name, capital, region, population, currency, live USD rate, timezones, phone code | Free |
+| `list_countries` | Paginated list of all 250+ countries | Free |
+| `search_countries` | Search countries by partial name | Free |
+| `get_states` | All states/provinces for a country | Basic+ |
+| `get_cities` | All cities for a state by numeric state ID | Basic+ |
+| `get_currency_rate` | Live USD exchange rate for a country's currency (updated every 4 hours) | Basic+ |
+| `geolocate_ip` | Country, region, city, coordinates, timezone, and EU membership for any IPv4/IPv6 | Basic+ |
+| `global_search` | Search across countries, states, and cities in one query | Free |
+
+## Installation
+
+### Claude Desktop
+
+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`
+
+```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.
+
+### Cursor
+
+Add the same block under `mcpServers` in Cursor's MCP configuration file (`~/.cursor/mcp.json`).
+
+### Manual build
+
+```bash
+git clone https://github.com/your-org/apogeoapi-mcp
+cd apogeoapi-mcp
+npm install
+npm run build
+```
+
+Then reference the built file directly:
+
+```json
+{
+  "mcpServers": {
+    "apogeoapi": {
+      "command": "node",
+      "args": ["/absolute/path/to/mcp-server/dist/index.js"],
+      "env": {
+        "APOGEOAPI_KEY": "apogeoapi_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
+      }
+    }
+  }
+}
+```
+
+## Getting an API key
+
+1. Create a free account at [app.apogeoapi.com](https://app.apogeoapi.com)
+2. Go to **API Keys** and generate a new key
+3. Paste the key into the `APOGEOAPI_KEY` environment variable above
+
+No credit card required for the Free plan (1,000 req/month).
+
+## Plan requirements
+
+| Feature | Free | Basic ($19/mo) | Starter ($29/mo) | Professional ($79/mo) |
+|---------|------|----------------|-------------------|-----------------------|
+| Countries (list, search, get) | Yes | Yes | Yes | Yes |
+| Global search | Yes | Yes | Yes | Yes |
+| States & cities | No | Yes | Yes | Yes |
+| Live currency rates | No | Yes | Yes | Yes |
+| IP geolocation | No | Yes | Yes | Yes |
+| Monthly requests | 1,000 | 15,000 | 100,000 | 500,000 |
+
+Upgrade at [app.apogeoapi.com/dashboard/billing](https://app.apogeoapi.com/dashboard/billing).
+
+## Environment variables
+
+| Variable | Required | Description |
+|----------|----------|-------------|
+| `APOGEOAPI_KEY` | Yes | Your API key from the dashboard |
+| `APOGEOAPI_BASE_URL` | No | Override the API base URL (default: `https://api.apogeoapi.com`) |
+
+## License
+
+MIT

package/dist/index.js

@@ -0,0 +1,21 @@
+#!/usr/bin/env node
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import { registerCountryTools } from './tools/countries.js';
+import { registerStateTools } from './tools/states.js';
+import { registerCityTools } from './tools/cities.js';
+import { registerCurrencyTools } from './tools/currency.js';
+import { registerIpTools } from './tools/ip.js';
+import { registerSearchTools } from './tools/search.js';
+const server = new McpServer({
+    name: 'apogeoapi',
+    version: '1.0.0',
+});
+registerCountryTools(server);
+registerStateTools(server);
+registerCityTools(server);
+registerCurrencyTools(server);
+registerIpTools(server);
+registerSearchTools(server);
+const transport = new StdioServerTransport();
+await server.connect(transport);

package/dist/lib/api-client.js

@@ -0,0 +1,17 @@
+const BASE = process.env.APOGEOAPI_BASE_URL ?? 'https://api.apogeoapi.com';
+function getKey() {
+    const key = process.env.APOGEOAPI_KEY;
+    if (!key)
+        throw new Error('APOGEOAPI_KEY environment variable is required');
+    return key;
+}
+export async function apiGet(path) {
+    const res = await fetch(`${BASE}${path}`, {
+        headers: { 'X-API-Key': getKey() },
+    });
+    if (!res.ok) {
+        const body = await res.text().catch(() => '');
+        throw new Error(`ApogeoAPI ${res.status}: ${body || res.statusText}`);
+    }
+    return res.json();
+}

package/dist/tools/cities.js

@@ -0,0 +1,21 @@
+import { z } from 'zod';
+import { apiGet } from '../lib/api-client.js';
+export function registerCityTools(server) {
+    server.tool('get_cities', 'Get all cities for a state/province by state ID. Requires Starter plan or above.', {
+        state_id: z.number().int().positive().describe('Numeric state ID (from get_states response)'),
+        page: z.number().int().positive().optional(),
+        limit: z.number().int().min(1).max(100).optional(),
+        fields: z.enum(['basic', 'standard', 'full']).optional(),
+    }, async ({ state_id, page, limit, fields }) => {
+        const params = new URLSearchParams();
+        if (page)
+            params.set('page', String(page));
+        if (limit)
+            params.set('limit', String(limit));
+        if (fields)
+            params.set('fields', fields);
+        const qs = params.toString() ? `?${params}` : '';
+        const data = await apiGet(`/v1/api/geo/states/${state_id}/cities${qs}`);
+        return { content: [{ type: 'text', text: JSON.stringify(data, null, 2) }] };
+    });
+}

package/dist/tools/countries.js

@@ -0,0 +1,41 @@
+import { z } from 'zod';
+import { apiGet } from '../lib/api-client.js';
+export function registerCountryTools(server) {
+    server.tool('get_country', '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.', {
+        code: z.string().min(2).max(3).describe('ISO2 (e.g. AR) or ISO3 (e.g. ARG) country code'),
+        fields: z.enum(['basic', 'standard', 'full']).optional().describe('Detail level: basic (fast), standard (default), full (all fields)'),
+    }, async ({ code, fields }) => {
+        const qs = fields ? `?fields=${fields}` : '';
+        const data = await apiGet(`/v1/api/geo/countries/${code.toUpperCase()}${qs}`);
+        return { content: [{ type: 'text', text: JSON.stringify(data, null, 2) }] };
+    });
+    server.tool('list_countries', 'List all countries with pagination. Returns basic info by default — add fields=full for all data.', {
+        page: z.number().int().positive().optional().describe('Page number (default: 1)'),
+        limit: z.number().int().min(1).max(100).optional().describe('Results per page (default: 50, max: 100)'),
+        fields: z.enum(['basic', 'standard', 'full']).optional().describe('Detail level'),
+    }, async ({ page, limit, fields }) => {
+        const params = new URLSearchParams();
+        if (page)
+            params.set('page', String(page));
+        if (limit)
+            params.set('limit', String(limit));
+        if (fields)
+            params.set('fields', fields);
+        const qs = params.toString() ? `?${params}` : '';
+        const data = await apiGet(`/v1/api/geo/countries${qs}`);
+        return { content: [{ type: 'text', text: JSON.stringify(data, null, 2) }] };
+    });
+    server.tool('search_countries', 'Search countries by name (e.g. "arg" finds Argentina). Returns paginated matches.', {
+        q: z.string().min(1).describe('Search query (partial name match)'),
+        page: z.number().int().positive().optional(),
+        limit: z.number().int().min(1).max(100).optional(),
+    }, async ({ q, page, limit }) => {
+        const params = new URLSearchParams({ q });
+        if (page)
+            params.set('page', String(page));
+        if (limit)
+            params.set('limit', String(limit));
+        const data = await apiGet(`/v1/api/geo/countries/search?${params}`);
+        return { content: [{ type: 'text', text: JSON.stringify(data, null, 2) }] };
+    });
+}

package/dist/tools/currency.js

@@ -0,0 +1,10 @@
+import { z } from 'zod';
+import { apiGet } from '../lib/api-client.js';
+export function registerCurrencyTools(server) {
+    server.tool('get_currency_rate', 'Get the live USD exchange rate for a country\'s currency. Updated every 4 hours. Requires Starter plan or above.', {
+        country_code: z.string().min(2).max(3).describe('ISO2 or ISO3 country code (e.g. AR, BR, JP)'),
+    }, async ({ country_code }) => {
+        const data = await apiGet(`/v1/api/geo/countries/${country_code.toUpperCase()}/currency-rate`);
+        return { content: [{ type: 'text', text: JSON.stringify(data, null, 2) }] };
+    });
+}

package/dist/tools/ip.js

@@ -0,0 +1,10 @@
+import { z } from 'zod';
+import { apiGet } from '../lib/api-client.js';
+export function registerIpTools(server) {
+    server.tool('geolocate_ip', 'Geolocate an IPv4 or IPv6 address — returns country, region, city, coordinates, timezone, and EU membership. Requires Starter plan or above.', {
+        address: z.string().describe('IPv4 or IPv6 address to geolocate (e.g. 8.8.8.8 or 2001:4860:4860::8888)'),
+    }, async ({ address }) => {
+        const data = await apiGet(`/v1/api/geo/ip/${address}`);
+        return { content: [{ type: 'text', text: JSON.stringify(data, null, 2) }] };
+    });
+}

package/dist/tools/search.js

@@ -0,0 +1,14 @@
+import { z } from 'zod';
+import { apiGet } from '../lib/api-client.js';
+export function registerSearchTools(server) {
+    server.tool('global_search', 'Search across countries, states, and cities in a single query. Returns the best matches from all geographic entity types.', {
+        q: z.string().min(1).describe('Search term (e.g. "Buenos Aires", "Pampas", "Cordoba")'),
+        limit: z.number().int().min(1).max(20).optional().describe('Max results (default: 10)'),
+    }, async ({ q, limit }) => {
+        const params = new URLSearchParams({ q });
+        if (limit)
+            params.set('limit', String(limit));
+        const data = await apiGet(`/v1/api/geo/search?${params}`);
+        return { content: [{ type: 'text', text: JSON.stringify(data, null, 2) }] };
+    });
+}

package/dist/tools/states.js

@@ -0,0 +1,21 @@
+import { z } from 'zod';
+import { apiGet } from '../lib/api-client.js';
+export function registerStateTools(server) {
+    server.tool('get_states', 'Get all states/provinces for a country. Requires Starter plan or above.', {
+        country_code: z.string().min(2).max(3).describe('ISO2 or ISO3 country code'),
+        page: z.number().int().positive().optional(),
+        limit: z.number().int().min(1).max(100).optional(),
+        fields: z.enum(['basic', 'standard', 'full']).optional(),
+    }, async ({ country_code, page, limit, fields }) => {
+        const params = new URLSearchParams();
+        if (page)
+            params.set('page', String(page));
+        if (limit)
+            params.set('limit', String(limit));
+        if (fields)
+            params.set('fields', fields);
+        const qs = params.toString() ? `?${params}` : '';
+        const data = await apiGet(`/v1/api/geo/countries/${country_code.toUpperCase()}/states${qs}`);
+        return { content: [{ type: 'text', text: JSON.stringify(data, null, 2) }] };
+    });
+}

package/package.json

@@ -0,0 +1,40 @@
+{
+  "name": "@apogeoapi/mcp",
+  "version": "1.0.0",
+  "description": "MCP server for ApogeoAPI — geographic data, live exchange rates & IP geolocation",
+  "type": "module",
+  "main": "dist/index.js",
+  "bin": {
+    "apogeoapi-mcp": "dist/index.js"
+  },
+  "scripts": {
+    "build": "tsc",
+    "dev": "tsx src/index.ts",
+    "start": "node dist/index.js",
+    "prepublishOnly": "npm run build"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.0.0",
+    "zod": "^3.22.0"
+  },
+  "devDependencies": {
+    "typescript": "^5.3.0",
+    "@types/node": "^20.0.0",
+    "tsx": "^4.0.0"
+  },
+  "files": ["dist"],
+  "keywords": ["mcp", "geolocation", "geography", "currency", "ip-geo", "apogeoapi"],
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/Ezleal/apo-geo-api.git",
+    "directory": "mcp-server"
+  },
+  "homepage": "https://apogeoapi.com"
+}