Overview

The PinMeTo MCP Server is a lightweight service that exposes authorized access to location data using a simple HTTP API. It sits between your location data store and client applications, enforcing authentication, access control, and a narrow protocol for retrieving location models. The server makes it easy to provide third-party integrations or internal tools with read-only access to curated location information without exposing your primary backend.

This server is particularly useful when you need to share location data with external partners, mobile apps, analytics pipelines, or widgets while retaining control over who can access which records, for how long, and under what conditions. It includes configuration options for API keys or token-based authentication, TLS support, and a small set of endpoints optimized for paginated and filtered retrieval of location records.

Features

Token- or API-key based authentication for controlled access
Read-only location endpoints (list, single record) with filtering and pagination
Configurable rate limits and request logging
Optional TLS/HTTPS configuration for secure transport
Simple configuration via environment variables or config file
Docker-friendly: run locally or in production with container tooling
Lightweight codebase that is easy to fork and extend for custom policies

Installation / Configuration

Clone the repository and run with Docker or directly with Node.js (or the project’s runtime). Replace placeholders below with your values.

Clone:

git clone https://github.com/PinMeTo/pinmeto-location-mcp.git
cd pinmeto-location-mcp

Environment variables (example .env):

# Server
PORT=8080
HOST=0.0.0.0

# Auth
AUTH_TYPE=api_key        # or "jwt"
API_KEYS=key1,key2

# Backend data source (example: URL to a location data API or DB)
LOCATIONS_SOURCE_URL=https://internal-api.example.com/locations

# TLS (optional)
TLS_ENABLED=false
TLS_CERT_PATH=/etc/ssl/certs/server.crt
TLS_KEY_PATH=/etc/ssl/private/server.key

# Rate limiting
RATE_LIMIT_REQUESTS=100
RATE_LIMIT_WINDOW_MS=60000

Run with Docker Compose:

# docker-compose.yml (simplified)
version: "3.8"
services:
  mcp-server:
    image: pinmeto/location-mcp:latest
    ports:
      - "8080:8080"
    env_file: .env
    restart: unless-stopped

Start:

docker-compose up -d
# or, with Node.js
npm install
npm start

Available Resources

GitHub repository: https://github.com/PinMeTo/pinmeto-location-mcp
Built-in API endpoints (see table below)
Sample client snippets in repository /examples
Configuration documented in CONFIG.md (check the repo for exact keys)
Logs and metrics are exposed via standard stdout (suitable for container logging)

API endpoints (example)

Endpoint	Method	Description
/health	GET	Server health check
/auth/token	POST	Exchange API key for short-lived token (if enabled)
/locations	GET	List locations with pagination & filters
/locations/{id}	GET	Retrieve a single location by ID

Note: Confirm exact paths and query parameters in the repository README or API docs.

Use Cases

Internal dashboard: Give your marketing or operations team read-only access to up-to-date location details (address, opening hours, coordinates) without exposing backend credentials. Example: the dashboard requests /locations?city=Oslo&page=1 with an API key header.
Third-party widget access: Provide partners with a token that allows them to fetch only approved location records. Use short-lived tokens via /auth/token to limit exposure if a key is compromised.
Mobile app integration: Mobile clients can fetch a filtered set of locations (e.g., nearby stores) using the /locations endpoint with latitude/longitude bounding parameters. Rate limiting prevents abusive polling by clients.
Analytics pipelines: Feed anonymized or aggregated location metadata into analytics jobs. The MCP server can act as a controlled access layer that enforces read-only semantics and logs queries for auditing.

Example request (curl):

curl -H "Authorization: ApiKey key1" \
  "https://mcp.example.com/locations?limit=25&page=1&city=Helsinki"

Example token exchange:

curl -X POST -H "Content-Type: application/json" \
  -d '{"apiKey":"key1"}' \
  https://mcp.example.com/auth/token

Operational Notes & Troubleshooting

Authentication: Verify AUTH_TYPE and API_KEYS (or JWT signing secret) are set correctly. Check server logs for 401 errors.
TLS: If TLS_ENABLED=true, ensure certificate and key files are readable by the container/user.
Performance: Use the RATE_LIMIT settings to balance throughput and abuse protection. Add caching in front (CDN or reverse proxy) if serving many clients.
Extensibility: The server is intended as a minimal gateway. Fork it to add custom authorization rules (per-partner filters) or to integrate with your internal identity provider.

For full implementation details, endpoint parameters, and example clients, see the repository: https://github.com/PinMeTo/pinmeto-location-mcp

PinMeTo MCP Server for Authorized Location Access