Ghana Post GPS MCP Server

A Model Context Protocol (MCP) server that converts Ghana Post GPS addresses into detailed location information including coordinates.

Features

• GPS Address Lookup: Convert Ghana Post GPS codes (e.g., "GA-554-3608") to detailed location information
• Address Validation: Validate GPS code format before processing
• Batch Processing: Look up multiple GPS addresses at once (up to 10)
• Nearby Coordinates: Generate coordinates within a specified radius of a known location
• Real API Integration: Uses the actual Ghana Post GPS API

Installation

Prerequisites

• Node.js 18.0.0 or higher
• npm

Setup

1. Clone or download this project

2. Install dependencies:

   npm install
   

3. Build the project:

   npm run build
   

Usage

Development Mode

npm run dev

Production Mode

npm run start

Testing

# Test server connection
npm run test

# Test GPS lookup
npm run test-lookup

Available Tools

1. lookup_gps_address

Converts a Ghana Post GPS address to detailed location information.

Input:

• gps_code (string): GPS address code (e.g., "GA-554-3608")

Output: Location details including coordinates, street, area, district, region, and postcode.

2. validate_gps_code

Validates if a string matches the Ghana Post GPS address format.

Input:

• gps_code (string): GPS code to validate

Output: Validation result with format information and examples.

3. batch_lookup_gps

Looks up multiple GPS addresses at once (maximum 10).

Input:

• gps_codes (array): Array of GPS codes to look up

Output: Results for all provided GPS codes with status information.

4. find_nearby_coordinates

Generates coordinates within a radius of a known GPS location.

Input:

• gps_code (string): Base GPS code
• radius_km (number, optional): Search radius in kilometers (default: 1)
• count (number, optional): Number of points to generate (default: 5)

Output: Base location info and array of nearby coordinates.

Claude Desktop Integration

To use this MCP server with Claude Desktop:

Windows

1. Edit %APPDATA%\\Claude\\claude_desktop_config.json
2. Add the server configuration:

{
  "mcpServers": {
    "ghana-post-gps": {
      "command": "node",
      "args": ["C:\\Users\\FRANKO\\OneDrive\\Desktop\\ghana-post-mcp\\dist\\index.js"],
      "env": {}
    }
  }
}

macOS

1. Edit ~/Library/Application Support/Claude/claude_desktop_config.json
2. Add the server configuration:

{
  "mcpServers": {
    "ghana-post-gps": {
      "command": "node",
      "args": ["/path/to/ghana-post-mcp/dist/index.js"],
      "env": {}
    }
  }
}

Linux

1. Edit ~/.config/Claude/claude_desktop_config.json
2. Add the server configuration with the appropriate path.

GPS Address Format

Ghana Post GPS addresses follow this format:

• Format: XX-YYY-ZZZZ
• XX: 2-letter region code (e.g., GA, AK, CP)
• YYY: 3-digit area code
• ZZZZ: 3-4 digit location code

Examples

• GA-554-3608 (Greater Accra)
• AK-039-5028 (Ashanti)
• CP-078-2542 (Central)

API Information

This server uses the Ghana Post GPS API endpoint:

• URL: https://ghanapostgps.sperixlabs.org/get-location
• Method: POST
• Content-Type: application/x-www-form-urlencoded

Development

Project Structure

ghana-post-mcp/
├── src/
│   └── index.ts          # Main MCP server implementation
├── dist/                 # Compiled JavaScript (after build)
├── package.json          # Dependencies and scripts
├── tsconfig.json         # TypeScript configuration
└── README.md            # This file

Building

npm run build

Cleaning

npm run clean

Error Handling

The server includes comprehensive error handling for:

• Invalid GPS code formats
• API connection failures
• Missing or malformed data
• Rate limiting considerations

Contributing

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Test thoroughly
5. Submit a pull request

License

MIT License

Support

For issues or questions about Ghana Post GPS addresses, refer to the official Ghana Post documentation or contact Ghana Post directly.