Epsg

npm version CI License: MIT Node.js MCP Built with Claude Code

日本語版 README

An MCP server that provides specialized knowledge and decision support for Coordinate Reference Systems (CRS) worldwide.

Global coverage through a 3-layer fallback:

1. Country Packs (Japan, US State Plane, UK National Grid, etc.) for expert-level recommendations
2. Automatic UTM zone calculation when no pack is available
3. Safe defaults (WGS84 / Web Mercator) as the final fallback

Coordinate transformation execution is delegated to mcp-server-proj, focusing on knowledge provision and decision support.

Features

• CRS Search: Search CRS by EPSG code, name, region, or prefecture
• Detailed Information: Get detailed information on geodetic datum, projection method, area of use, accuracy characteristics, and more
• Regional Listings: List CRS available in Japan/Global with purpose-specific recommendations
• CRS Recommendation: Recommend the optimal CRS for each purpose and location (with multi-zone support for Hokkaido and Okinawa)
• Usage Validation: Verify the validity of CRS selection and present issues with suggestions for improvement
• Transformation Routing: Propose optimal transformation paths using BFS graph search (with reverse transformation support)
• CRS Comparison: Compare CRS from 7 perspectives (datum, projection, accuracy, distortion, compatibility, etc.)
• Best Practices: CRS usage guidance on 10 topics (surveying, web mapping, data exchange, etc.)
• Troubleshooting: Diagnose CRS problems by symptoms (coordinate shifts, calculation errors, etc.)
• Country Pack System: Extensible regional expertise (Japan, US, UK available; easily add more)
• Offline Operation: Local database requires no external API
• Internationalized: Tool definitions and parameter descriptions in English (usable by AI agents in any language)
• Graceful Degradation: Works anywhere via UTM fallback even without region-specific packs

Installation

npm install @shuji-bonji/epsg-mcp

Or run directly:

npx @shuji-bonji/epsg-mcp

Usage

Claude Desktop

Add to claude_desktop_config.json:

{
	"mcpServers": {
		"epsg": {
			"command": "npx",
			"args": ["@shuji-bonji/epsg-mcp"]
		}
	}
}

Enabling Additional Country Packs

By default, only the Japan pack is loaded. To enable additional packs (e.g., US, UK), set the EPSG_PACKS environment variable:

{
	"mcpServers": {
		"epsg": {
			"command": "npx",
			"args": ["@shuji-bonji/epsg-mcp"],
			"env": {
				"EPSG_PACKS": "jp,us,uk"
			}
		}
	}
}

Available packs: jp (Japan), us (United States), uk/gb (United Kingdom)

Language Settings

By default, output is in English. To get Japanese output, set the EPSG_LANG environment variable:

{
	"mcpServers": {
		"epsg": {
			"command": "npx",
			"args": ["@shuji-bonji/epsg-mcp"],
			"env": {
				"EPSG_LANG": "ja"
			}
		}
	}
}

MCP Inspector

npx @modelcontextprotocol/inspector npx @shuji-bonji/epsg-mcp

Tools

search_crs

Search CRS by keyword.

// Input
{
  query: string;           // Search keyword (e.g., "JGD2011", "4326", "Tokyo")
  type?: "geographic" | "projected" | "compound" | "vertical" | "engineering";
  region?: "Japan" | "Global";
  limit?: number;          // Default: 10, max: 100
}

// Output
{
  results: CrsInfo[];
  totalCount: number;
}

Usage Examples:

• "Search for CRS related to JGD2011"
• "Find projected coordinate systems available in Tokyo"
• "Get information about EPSG code 6677"

get_crs_detail

Get detailed CRS information by EPSG code.

// Input
{
  code: string;  // "EPSG:6677" or "6677"
}

// Output
{
  code: string;
  name: string;
  type: CrsType;
  datum?: DatumInfo;
  projection?: ProjectionInfo;
  areaOfUse: AreaOfUse;
  accuracy?: AccuracyInfo;
  remarks?: string;
  useCases?: string[];
  // ...
}

Usage Examples:

• "Tell me the details of EPSG:6677"
• "What are the characteristics of Web Mercator (3857)?"

list_crs_by_region

Get available CRS list and recommendations by region.

// Input
{
  region: "Japan" | "Global";
  type?: CrsType;
  includeDeprecated?: boolean;  // Default: false
}

// Output
{
  region: string;
  crsList: CrsInfo[];
  recommendedFor: {
    general: string;
    survey: string;
    webMapping: string;
  };
}

Usage Examples:

• "List CRS available in Japan"
• "What global geographic coordinate systems are there?"

recommend_crs

Recommend optimal CRS based on purpose and location.

// Input
{
  purpose: "web_mapping" | "distance_calculation" | "area_calculation" |
           "survey" | "navigation" | "data_exchange" | "data_storage" | "visualization";
  location: {
    country?: string;      // "Japan" | "Global"
    region?: string;       // "Kanto", "Hokkaido", "Main Island", "Sakishima", etc.
    prefecture?: string;   // "Tokyo", "Hokkaido", etc.
    city?: string;         // "Sapporo", "Naha", etc. (for multi-zone support)
    boundingBox?: BoundingBox;
    centerPoint?: { lat: number; lng: number };
  };
  requirements?: {
    accuracy?: "high" | "medium" | "low";
    distortionTolerance?: "minimal" | "moderate" | "flexible";
    interoperability?: string[];  // e.g., ["GIS", "CAD", "Web"]
  };
}

// Output
{
  primary: RecommendedCrs;    // Recommended CRS (with score, pros, cons)
  alternatives: RecommendedCrs[];
  reasoning: string;
  warnings?: string[];        // Warnings for areas spanning multiple zones
}

Usage Examples:

• "What's the best CRS for distance calculation around Tokyo?"
• "What CRS should I use for surveying in Sapporo, Hokkaido?"
• "I want to display a map of all Japan in a web app"

validate_crs_usage

Validate whether a specified CRS is appropriate for a specific purpose and location.

// Input
{
  crs: string;               // "EPSG:3857" or "3857"
  purpose: Purpose;          // Same as recommend_crs
  location: LocationSpec;    // Same as recommend_crs
}

// Output
{
  isValid: boolean;
  score: number;             // Suitability 0-100
  issues: ValidationIssue[]; // List of issues
  suggestions: string[];     // Improvement suggestions
  betterAlternatives?: RecommendedCrs[];  // Alternatives when score is low
}

Detected Issues Examples:

• DEPRECATED_CRS: Using deprecated CRS
• AREA_DISTORTION: Area calculation with Web Mercator
• ZONE_MISMATCH: Using Zone I (for Nagasaki) in Tokyo
• GEOJSON_INCOMPATIBLE: Outputting GeoJSON with projected CRS

Usage Examples:

• "Is it OK to use Web Mercator for area calculation in Hokkaido?"
• "Any issues with storing survey data in Japan using EPSG:4326?"

suggest_transformation

Suggest optimal transformation path between two CRS.

// Input
{
  sourceCrs: string;    // "EPSG:4301" or "4301"
  targetCrs: string;    // "EPSG:6668" or "6668"
  location?: {
    country?: string;
    prefecture?: string;
    boundingBox?: BoundingBox;
  };
}

// Output
{
  directPath: TransformationPath | null;  // Direct transformation path
  viaPaths: TransformationPath[];         // Indirect transformation paths
  recommended: TransformationPath;        // Recommended path
  warnings: string[];
}

TransformationPath:

• steps: Array of transformation steps (from, to, method, accuracy, isReverse)
• totalAccuracy: Overall accuracy
• complexity: "simple" | "moderate" | "complex"

Features:

• BFS graph search for paths up to 4 steps
• Automatic consideration of reverse transformations (reversible: true)
• Warnings when using deprecated CRS (Tokyo Datum, JGD2000)
• Accuracy warnings for large area data transformation

Usage Examples:

• "How to transform from Tokyo Datum to JGD2011?"
• "Show me the transformation path from WGS84 to Web Mercator"

compare_crs

Compare two CRS from various perspectives.

// Input
{
  crs1: string;  // "EPSG:4326" or "4326"
  crs2: string;  // "EPSG:6668" or "6668"
  aspects?: ComparisonAspect[];  // Specify comparison aspects (all if omitted)
}

// ComparisonAspect
"datum" | "projection" | "area_of_use" | "accuracy" | "distortion" | "compatibility" | "use_cases"

// Output
{
  comparison: ComparisonResult[];  // Comparison results for each aspect
  summary: string;                 // Summary
  recommendation: string;          // Recommendation
  transformationNote?: string;     // Notes on transformation
}

Comparison Aspects:

• datum: Datum comparison (e.g., WGS84 vs JGD2011 are practically identical)
• projection: Projection comparison
• area_of_use: Area of use comparison
• accuracy: Accuracy characteristics comparison
• distortion: Distortion characteristics comparison
• compatibility: GIS/Web/CAD/GPS compatibility comparison
• use_cases: Use case suitability comparison (score-based)

Usage Examples:

• "What's the difference between WGS84 and JGD2011?"
• "Compare Web Mercator and geographic CRS"
• "Compare JGD2000 and JGD2011 from the datum perspective"

get_best_practices

Get best practices for CRS usage.

// Input
{
  topic: "japan_survey" | "web_mapping" | "data_exchange" | "coordinate_storage" |
         "mobile_gps" | "cross_border" | "historical_data" | "gis_integration" |
         "precision_requirements" | "projection_selection";
  context?: string;  // Additional context (optional, max 500 characters)
}

// Output
{
  topic: string;
  description: string;
  practices: Practice[];       // Recommended practices
  commonMistakes: Mistake[];   // Common mistakes
  relatedTopics: string[];     // Related topics
  references: Reference[];     // Reference materials
}

Practice:

• title: Practice name
• description: Description
• priority: "must" | "should" | "may"
• rationale: Rationale
• example?: Concrete example

Usage Examples:

• "What are the best practices for surveying in Japan?"
• "How to choose coordinate systems when creating web maps"
• "What to watch out for when exchanging data in GeoJSON"

troubleshoot

Troubleshoot CRS-related problems.

// Input
{
  symptom: string;  // Symptom (2-500 characters)
  context?: {
    sourceCrs?: string;   // Source CRS
    targetCrs?: string;   // Target CRS
    location?: string;    // Target region
    tool?: string;        // Tool being used
    magnitude?: string;   // Magnitude of shift
  };
}

// Output
{
  matchedSymptom: string;         // Matched symptom category
  possibleCauses: Cause[];        // Possible causes (with likelihood)
  diagnosticSteps: DiagnosticStep[]; // Diagnostic steps
  suggestedSolutions: Solution[]; // Solutions
  relatedBestPractices: string[]; // Related best practices
  confidence: "high" | "medium" | "low";  // Diagnosis confidence
}

Supported Symptoms:

• Coordinates shift by hundreds of meters to kilometers (Tokyo Datum issues, etc.)
• Coordinates shift by 1-several meters (transformation accuracy limits, etc.)
• Coordinates shift by centimeters to tens of centimeters (WGS84/JGD2011 difference, etc.)
• Area/distance calculations are incorrect (Web Mercator distortion, etc.)
• Data doesn't display (CRS mismatch, etc.)
• Coordinate transformation errors (unregistered parameters, etc.)

Usage Examples:

• "Coordinates are off by 400m"
• "Area calculation results are wrong"
• "Old data and new data don't align"

Supported CRS

Japan (JGD2011)

EPSG	Name	Usage
6668	JGD2011	Geographic CRS (reference)
6669-6687	Japan Plane Rectangular CS I-XIX	Surveying, large-scale maps
4612	JGD2000	Legacy (deprecated)

United States (NAD83)

EPSG	Name	Usage
4269	NAD83	Geographic CRS (standard)
6318	NAD83(2011)	Latest realization
5070	NAD83 / Conus Albers	Area calculations
2229	NAD83 / California zone 5	State Plane example
2263	NAD83 / New York Long Island	State Plane example

United Kingdom (OSGB36/ETRS89)

EPSG	Name	Usage
4277	OSGB36	Geographic CRS (legacy)
4258	ETRS89	Geographic CRS (modern)
27700	British National Grid	Surveying, mapping
2157	Irish Transverse Mercator	Northern Ireland

Global

EPSG	Name	Usage
4326	WGS 84	GPS/GeoJSON standard
3857	Web Mercator	Web map display
326xx	UTM zones	Distance/area calculation

Extended CRS Support (Optional)

By default, this server provides CRS data for Japan and major global systems. For access to the complete EPSG registry (10,000+ CRS), you can optionally enable SQLite support.

Setup

1. Download EPSG Database

# Using the built-in script
npm run epsg:download-db

# Or specify a custom path
npx tsx scripts/download-epsg-db.ts ./path/to/epsg.db

2. Install sql.js (only if npm install did not install it)

sql.js is already listed in optionalDependencies, so it is normally installed automatically when you run npm install @shuji-bonji/epsg-mcp. You only need this step if the optional dependency was skipped (e.g., by --no-optional):

npm install sql.js

3. Configure Environment

Set the EPSG_DB_PATH environment variable:

export EPSG_DB_PATH="/path/to/epsg.db"

Or configure in Claude Desktop's claude_desktop_config.json:

{
	"mcpServers": {
		"epsg": {
			"command": "npx",
			"args": ["@shuji-bonji/epsg-mcp"],
			"env": {
				"EPSG_DB_PATH": "/path/to/epsg.db"
			}
		}
	}
}

Data Source

The EPSG database is provided by PROJ, which redistributes the IOGP EPSG Geodetic Parameter Dataset. Please refer to the EPSG Terms of Use for licensing information.

Development

# Install dependencies
npm install

# Build
npm run build

# Test
npm test

# Watch mode
npm run test:watch

Documentation

• Usage Examples - Practical scenarios showing how EPSG MCP helps with CRS decisions
• Creating Country Packs - Guide for adding new country/region support

Roadmap

• Phase 1 ✅: search_crs, get_crs_detail, list_crs_by_region
• Phase 2 ✅: recommend_crs, validate_crs_usage
• Phase 3 ✅: suggest_transformation, compare_crs
• Phase 4 ✅: get_best_practices, troubleshoot
• Phase 5 ✅: Internationalization & multi-region support (Country Pack system, UTM fallback, optional SQLite backend, JP/US/UK packs)

Related Projects

• mcp-server-proj - MCP server for coordinate transformation execution
• EPSG.io - EPSG coordinate system database

License

MIT License - see LICENSE for details.