Epsg Mcp Server

EPSG MCP サーバー

日本語版 README

世界中の座標参照系（CRS）について、専門知識と選定支援を提供する MCP サーバーです。

3 層のフォールバックによるグローバルな対応範囲：

1. 国別パック（日本、米国の州平面座標系、英国のナショナルグリッドなど）による専門家レベルの推奨
2. パックが利用できない場合の自動 UTM ゾーン計算
3. 最終的なフォールバックとしての安全なデフォルト（WGS84／Web メルカトル）

座標変換の実行は mcp-server-proj に委任し、知識の提供と選定支援に重点を置いています。

機能

• CRS 検索：EPSG コード、名称、地域、都道府県から CRS を検索します
• 詳細情報：測地基準系、投影法、適用範囲、精度特性などの詳細情報を取得します
• 地域別一覧：目的に応じた推奨 CRS とともに、日本／全世界で利用可能な CRS を一覧表示します
• CRS 推奨：目的と場所に応じた最適な CRS を推奨します（北海道と沖縄では複数ゾーンに対応）
• 用途検証：CRS の選定が適切か確認し、改善案とともに問題点を提示します
• 変換経路の提案：BFS グラフ検索で最適な変換経路を提案します（逆変換にも対応）
• CRS 比較：7 つの観点（測地基準系、投影法、精度、歪み、互換性など）から CRS を比較します
• ベストプラクティス：10 のトピック（測量、ウェブマッピング、データ交換など）について CRS の利用方法を案内します
• トラブルシューティング：症状（座標のずれ、計算エラーなど）から CRS の問題を診断します
• 国別パックシステム：地域に関する専門知識を拡張できます（日本、米国、英国に対応。さらに簡単に追加可能）
• オフライン動作：ローカルデータベースを使用するため、外部 API は不要です
• 多言語対応：ツール定義とパラメーターの説明は英語です（あらゆる言語の AI エージェントで利用可能）
• 段階的な機能縮退：地域別パックがなくても、UTM フォールバックによりどこでも動作します

インストール

npm install @shuji-bonji/epsg-mcp

または、次のコマンドを直接実行します。

npx @shuji-bonji/epsg-mcp

使い方

Claude Desktop

claude_desktop_config.json に追加します。

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

追加の国別パックを有効にする

デフォルトでは、日本パックのみが読み込まれます。追加のパック（米国、英国など）を有効にするには、EPSG_PACKS 環境変数を設定します。

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

利用可能なパック：jp（日本）、us（米国）、uk／gb（英国）

言語設定

デフォルトの出力言語は英語です。日本語で出力するには、EPSG_LANG 環境変数を設定します。

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

ローカルビルドから実行する（開発）

未リリースのビルドを試すには、npx の代わりに build/index.js を MCP クライアントに指定します。

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"
			}
		}
	}
}

注意事項：

• build/index.js は npm run build で生成されます。ソースを変更した後は、再ビルドして MCP クライアントを再起動してください。
• Claude Desktop などの GUI アプリケーションは、シェルの PATH を引き継がないことがあります。クライアントから spawn node ENOENT と報告された場合は、"node" を which node で表示される絶対パスに置き換えてください。
• Claude Code では、同じ設定を次の 1 つのコマンドで登録できます：claude mcp add epsg-dev -e EPSG_PACKS=jp,us,uk -- node /absolute/path/to/epsg-mcp/build/index.js
• npx @modelcontextprotocol/inspector node build/index.js を実行すると、MCP Inspector でローカルビルドを開けます。

MCP Inspector

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

ツール

search_crs

キーワードで CRS を検索します。

// 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;
}

使用例：

• 「JGD2011 に関連する CRS を検索して」
• 「東京で利用できる投影座標系を探して」
• 「EPSG コード 6677 の情報を取得して」

get_crs_detail

EPSG コードで CRS の詳細情報を取得します。

// 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[];
  // ...
}

使用例：

• 「EPSG:6677 の詳細を教えて」
• 「Web Mercator（3857）の特性は？」

list_crs_by_region

地域ごとに利用可能な CRS の一覧と推奨情報を取得します。

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

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

使用例：

• 「日本で利用できる CRS を一覧表示して」
• 「どのような世界測地系がある？」

recommend_crs

目的と場所に基づいて、最適な CRS を推奨します。

// 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
}

使用例：

• 「東京周辺で距離を計算するのに最適な CRS は？」
• 「北海道札幌市で測量する場合、どの CRS を使えばよい？」
• 「Web アプリですべての日本地図を表示したい」

validate_crs_usage

指定した CRS が、特定の目的や場所に適しているかを検証します。

// 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
}

検出される問題の例：

• DEPRECATED_CRS：非推奨の CRS の使用
• AREA_DISTORTION：Web Mercator での面積計算
• ZONE_MISMATCH：東京で長崎向けの Zone I を使用
• GEOJSON_INCOMPATIBLE：投影 CRS で GeoJSON を出力

使用例：

• 「北海道で面積計算に Web Mercator を使っても大丈夫？」
• 「EPSG:4326 を使って日本の測量データを保存する際、問題はある？」

suggest_transformation

2 つの 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：変換ステップの配列（from、to、method、accuracy、isReverse）
• totalAccuracy：全体の精度
• complexity：「simple」|「moderate」|「complex」

機能：

• 最大 4 ステップまでの経路を BFS グラフ探索で検索
• 逆変換（reversible: true）を自動的に考慮
• 非推奨の CRS（Tokyo Datum、JGD2000）を使用する場合に警告
• 広域データの変換時に精度に関する警告を表示

使用例：

• 「Tokyo Datum から JGD2011 への変換方法は？」
• 「WGS84 から Web Mercator への変換経路を表示して」

compare_crs

2 つの CRS をさまざまな観点から比較します。

// 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
}

比較項目：

• datum：測地系の比較（例：WGS84 と JGD2011 は実質的に同一）
• projection：投影法の比較
• area_of_use：使用範囲の比較
• accuracy：精度特性の比較
• distortion：歪み特性の比較
• compatibility：GIS／Web／CAD／GPS との互換性の比較
• use_cases：用途への適合性の比較（スコアベース）

使用例：

• 「WGS84 と JGD2011 の違いは？」
• 「Web Mercator と地理座標 CRS を比較して」
• 「測地系の観点から JGD2000 と JGD2011 を比較して」

get_best_practices

CRS の使用に関するベストプラクティスを取得します。

// 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：プラクティス名
• description：説明
• priority：「must」|「should」|「may」
• rationale：根拠
• example?：具体例

使用例：

• 「日本で測量を行う際のベストプラクティスは？」
• 「Web 地図を作成するときの座標系の選び方」
• 「GeoJSON でデータを交換するときの注意点は？」

troubleshoot

CRS 関連の問題をトラブルシューティングします。

// 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
}

対応する症状：

• 座標が数百メートルから数キロメートルずれる（Tokyo Datum の問題など）
• 座標が 1 メートルから数メートルずれる（変換精度の限界など）
• 座標が数センチメートルから数十センチメートルずれる（WGS84 と JGD2011 の違いなど）
• 面積／距離の計算が正しくない（Web Mercator の歪みなど）
• データが表示されない（CRS の不一致など）
• 座標変換エラー（パラメーターが登録されていないなど）

使用例：

• 「座標が 400m ずれている」
• 「面積計算の結果が間違っている」
• 「古いデータと新しいデータの位置が合わない」

対応 CRS

日本（JGD2011）

EPSG	Name	Usage
6668	JGD2011	地理CRS（参照）
6669-6687	Japan Plane Rectangular CS I-XIX	測量、大縮尺地図
4612	JGD2000	旧版（非推奨）

米国（NAD83）

EPSG	Name	Usage
4269	NAD83	地理CRS（標準）
6318	NAD83(2011)	最新の実現
5070	NAD83 / Conus Albers	面積計算
2229	NAD83 / California zone 5	State Plane の例
2263	NAD83 / New York Long Island	State Plane の例

英国（OSGB36/ETRS89）

EPSG	Name	Usage
4277	OSGB36	地理CRS（旧版）
4258	ETRS89	地理CRS（現行）
27700	British National Grid	測量、地図作成
2157	Irish Transverse Mercator	北アイルランド

グローバル

EPSG	Name	Usage
4326	WGS 84	GPS/GeoJSON 標準
3857	Web Mercator	ウェブ地図表示
326xx	UTM zones	距離・面積の計算

拡張CRSサポート（オプション）

デフォルトでは、このサーバーは日本および主要なグローバル座標系のCRSデータを提供します。EPSGレジストリ全体（10,000件以上のCRS）にアクセスするには、SQLiteサポートをオプションで有効にできます。

セットアップ

1. EPSGデータベースのダウンロード

# 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. sql.js のインストール（npm installでインストールされなかった場合のみ）

sql.jsはすでにoptionalDependenciesに記載されているため、通常はnpm install @shuji-bonji/epsg-mcpを実行すると自動的にインストールされます。この手順が必要なのは、オプションの依存関係がスキップされた場合（例：--no-optionalを指定した場合）のみです。

npm install sql.js

3. 環境設定

EPSG_DB_PATH環境変数を設定します。

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

または、Claude Desktop のclaude_desktop_config.jsonで設定します。

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

データソース

EPSGデータベースはPROJによって提供されており、IOGP EPSG Geodetic Parameter Datasetを再配布しています。ライセンス情報については、EPSG利用規約を参照してください。

開発

Node.js 22 以降が必要です。

# Install dependencies
npm install

# Build
npm run build

# Test
npm test

# Watch mode
npm run test:watch

ドキュメント

• 使用例 - EPSG MCP が CRS の選択に役立つ実践的なシナリオ
• 国別パックの作成 - 新しい国・地域のサポートを追加するためのガイド

ロードマップ

• フェーズ 1 ✅：search_crs、get_crs_detail、list_crs_by_region
• フェーズ 2 ✅：recommend_crs、validate_crs_usage
• フェーズ 3 ✅：suggest_transformation、compare_crs
• フェーズ 4 ✅：get_best_practices、troubleshoot
• フェーズ 5 ✅：国際化と複数地域のサポート（Country Pack システム、UTM フォールバック、オプションの SQLite バックエンド、日本・米国・英国のパック）

関連プロジェクト

• mcp-server-proj - 座標変換を実行する MCP サーバー
• EPSG.io - EPSG 座標系データベース

ライセンス

MIT License - 詳細はLICENSEを参照してください。