epsg-mcp
The EPSG MCP server provides specialized knowledge and decision support for Coordinate Reference Systems (CRS) worldwide, helping users make informed choices for mapping, surveying, and spatial data projects.
Core Capabilities:
CRS Search & Information: Search by EPSG code, name, region, or prefecture with filtering by type; get detailed information on datum, projection, area of use, and accuracy
Regional CRS Management: List CRS by region (Japan, Global) with purpose-specific recommendations, including Japan's Plane Rectangular CS Zones I-XIX
CRS Recommendation: Get optimal CRS recommendations based on purpose (web mapping, surveying, distance/area calculation, navigation, data exchange, storage, visualization) and location, with multi-zone support for regions like Hokkaido and Okinawa
CRS Validation: Verify if a CRS is appropriate for specific purposes and locations, detecting issues like deprecated usage, distortion problems, zone mismatches, and GeoJSON incompatibility
Transformation Planning: Find optimal multi-step transformation paths (up to 4 steps) between CRS using BFS graph search, with accuracy information, reverse transformation support, and warnings about cumulative errors
CRS Comparison: Compare two CRS across 7 perspectives: datum, projection method, area of use, accuracy, distortion characteristics, compatibility (GIS/Web/CAD/GPS), and use case suitability
Best Practices Guidance: Access guidance on 10 topics including surveying in Japan, web mapping, data exchange, coordinate storage, mobile GPS, cross-border data, historical data handling, GIS integration, precision requirements, and projection selection
Troubleshooting: Diagnose CRS-related problems like coordinate shifts (cm to km scale), calculation errors, display issues, and transformation failures with diagnostic steps and solutions
Coverage:
Japan: JGD2011, Plane Rectangular CS Zones I-XIX, legacy Tokyo Datum and JGD2000
United States: NAD83, NAD83(2011), State Plane systems, and specialized projections
United Kingdom: OSGB36, ETRS89, British National Grid, Irish Transverse Mercator
Global: WGS84, Web Mercator, UTM zones
Extensible: Country pack system for adding new regions, with automatic UTM fallback for areas without specific packs
Optional: Full EPSG registry (10,000+ CRS) via SQLite database
Additional Features:
Offline Operation: Works without external API dependencies using local database
Internationalization: Tools and descriptions are internationalized for use by AI agents in multiple languages
EPSG MCP Server
An MCP server that provides specialized knowledge and decision support for Coordinate Reference Systems (CRS) worldwide.
Global coverage through a 3-layer fallback:
Country Packs (Japan, US State Plane, UK National Grid, etc.) for expert-level recommendations
Automatic UTM zone calculation when no pack is available
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
Related MCP server: chuk-mcp-geocoder
Installation
npm install @shuji-bonji/epsg-mcpOr run directly:
npx @shuji-bonji/epsg-mcpUsage
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"
}
}
}
}Running from a local build (development)
To try an unreleased build, point your MCP client at build/index.js instead of npx:
git clone https://github.com/shuji-bonji/epsg-mcp.git
cd epsg-mcp
npm ci
npm run build{
"mcpServers": {
"epsg-dev": {
"command": "node",
"args": ["/absolute/path/to/epsg-mcp/build/index.js"],
"env": {
"EPSG_PACKS": "jp,us,uk"
}
}
}
}Notes:
build/index.jsis generated bynpm run build; rebuild and restart the MCP client after changing the source.GUI applications such as Claude Desktop may not inherit your shell
PATH. If the client reportsspawn node ENOENT, replace"node"with the absolute path printed bywhich node.With Claude Code, the same can be registered in one command:
claude mcp add epsg-dev -e EPSG_PACKS=jp,us,uk -- node /absolute/path/to/epsg-mcp/build/index.jsnpx @modelcontextprotocol/inspector node build/index.jsopens the local build in MCP Inspector.
MCP Inspector
npx @modelcontextprotocol/inspector npx @shuji-bonji/epsg-mcpTools
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 CRSAREA_DISTORTION: Area calculation with Web MercatorZONE_MISMATCH: Using Zone I (for Nagasaki) in TokyoGEOJSON_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 accuracycomplexity: "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 comparisonarea_of_use: Area of use comparisonaccuracy: Accuracy characteristics comparisondistortion: Distortion characteristics comparisoncompatibility: GIS/Web/CAD/GPS compatibility comparisonuse_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 namedescription: Descriptionpriority: "must" | "should" | "may"rationale: Rationaleexample?: 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
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.dbInstall sql.js (only if
npm installdid 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.jsConfigure 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
Requires Node.js 22 or later.
# Install dependencies
npm install
# Build
npm run build
# Test
npm test
# Watch mode
npm run test:watchDocumentation
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.
Available Tools
9 toolscompare_crsA
Compare two CRS from various perspectives. Compares datum, projection method, area of use, accuracy, distortion characteristics, compatibility, and use case suitability. Explains which is better suited for specific purposes.
Inputs: crs1 (required), crs2 (required), aspects.
get_best_practicesC
Get CRS best practices for specific topics. Covers surveying in Japan, web mapping, data exchange, coordinate storage, mobile GPS, cross-border data, historical data, GIS integration, precision requirements, and projection selection. Provides recommended practices, common mistakes, and reference materials.
Inputs: topic (required), context.
get_crs_detailC
Get detailed information for a specific EPSG code. Includes datum, projection method, area of use, accuracy characteristics, and intended use cases.
Inputs: code (required).
list_crs_by_regionB
Get available CRS list for a region with purpose-based recommendations. Japan includes Plane Rectangular CS (Zones I-XIX), Global includes WGS84 and UTM zones.
Inputs: region (required), type, includeDeprecated.
recommend_crsB
Recommend the optimal CRS based on purpose and location. Supports web mapping, distance/area calculation, surveying, navigation, data exchange, etc. Full support for Japan Plane Rectangular CS (Zones I-XIX) including multi-zone regions like Hokkaido and Okinawa.
Inputs: purpose (required), location (required), requirements.
search_crsA
Search EPSG Coordinate Reference Systems (CRS) by keyword. Searchable by EPSG code, name, region name, or prefecture name. Covers Japanese JGD2011 CRS family, global WGS84, Web Mercator, and more.
Inputs: query (required), type, region, limit.
suggest_transformationA
Suggest transformation paths between two CRS. Covers Tokyo Datum to JGD2011, WGS84 to Plane Rectangular CS, etc. Searches multi-step paths, provides accuracy info, and warns about cumulative errors.
Inputs: sourceCrs (required), targetCrs (required), location.
troubleshootB
Troubleshoot CRS-related problems. Diagnoses coordinate shifts (cm, m, km scale), area/distance calculation errors, data not displaying, and transformation errors. Identifies causes, provides diagnostic steps, and solutions.
Inputs: symptom (required), context.
validate_crs_usageB
Validate whether a CRS is appropriate for a specific purpose and location. Detects deprecated CRS usage, area/distance calculation distortion issues, inappropriate zone selection for surveying, and provides improvement suggestions.
Inputs: crs (required), purpose (required), location (required).
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 9 tools
Every tool has a clearly distinct purpose with no ambiguity: compare_crs compares two CRS, get_best_practices provides guidelines, get_crs_detail gives detailed info, list_crs_by_region lists region-specific options, recommend_crs suggests optimal choices, search_crs searches by keywords, suggest_transformation finds transformation paths, troubleshoot diagnoses problems, and validate_crs_usage validates appropriateness. The descriptions clearly differentiate each tool's function, making misselection unlikely.
All tool names follow a consistent verb_noun pattern (e.g., compare_crs, get_best_practices, list_crs_by_region) using snake_case throughout. The verbs are descriptive and aligned with the actions (compare, get, list, recommend, search, suggest, troubleshoot, validate), creating a predictable and readable naming convention across the entire set.
With 9 tools, the count is well-scoped for the EPSG/CRS domain, covering key operations like searching, recommending, comparing, validating, troubleshooting, and providing detailed information. Each tool earns its place by addressing specific needs in coordinate reference system management, avoiding both thin coverage and overwhelming complexity.
The tool set provides complete lifecycle coverage for the EPSG/CRS domain: from discovery (search_crs, list_crs_by_region) and detailed information (get_crs_detail) to selection (recommend_crs, validate_crs_usage), comparison (compare_crs), transformation (suggest_transformation), troubleshooting (troubleshoot), and best practices (get_best_practices). There are no obvious gaps, ensuring agents can handle end-to-end workflows without dead ends.
Maintenance
Related MCP Connectors
MCP server for aerospace calculations: orbital mechanics, ephemeris, DSN operations, ...
Hosted MCP server for finding authoritative primary data sources and official portals.
Canonical British Columbia Property Intelligence & Risk Screening MCP Server.
Related MCP Servers
- AlicenseNot gradedqualityFmaintenanceAn experimental MCP server providing spatial context for LLMs by interfacing with French Geoplateforme services. It enables tasks such as geocoding, altitude lookups, and querying administrative, cadastral, or urban planning data.10 npm4MIT
- AlicenseAqualityFmaintenanceAn MCP server providing geocoding and place discovery services via Nominatim and OpenStreetMap. It enables users to perform forward and reverse geocoding, extract bounding boxes, and find nearby places or administrative hierarchies.10Apache 2.0
- AlicenseAqualityBmaintenanceMCP server for Swiss federal geodata -- maps, elevation, geocoding, cadastral extracts, and downloadable datasets via Swisstopo APIs.2062 PyPI12MIT
- AlicenseAqualityDmaintenanceA Model Context Protocol server for coordinate system transformations and map projections, supporting EPSG codes, WKT, and Proj formats.22MIT