DOCSEARCHbyAlgolia
Submit Docs

MLIT Data Platform MCP Server

repository·main·Indexed 41 days ago

https://github.com/mlit-data-platform/mlit-dpf-mcp

An MCP (Model Context Protocol) server version 0.1.0 that enables LLMs to interact with the Ministry of Land, Infrastructure, Transport and Tourism (MLIT) Data Platform API. It provides tools for natural language data discovery, keyword and geographic searches (rectangle or radius), attribute-based filtering, and retrieval of data catalogs, download URLs, and thumbnails via a GraphQL-based MLITClient.

Tokens
9.7K
Snippets
35
Records
51
Agent score
51%

What's inside MLIT Data Platform MCP

  1. Overview of MLIT DATA PLATFORM MCP Server

    main

    The MLIT DATA PLATFORM MCP Server (alpha version) is a Model Context Protocol (MCP) server that connects Large Language Models (LLMs) to the MLIT Data Platform API. It allows users to search, view, and download data from the Ministry of Land, Infrastructure, Transport and Tourism (MLIT) using natural language via MCP-compatible hosts like Claude Desktop.

    Key capabilities include keyword searches, location-based searches (rectangle or radius), attribute-based filtering, and retrieving detailed data, catalogs, or download URLs.

  2. Install and Setup MLIT DATA PLATFORM MCP Server

    main

    Follow these steps to set up the MCP server for use with Claude Desktop.

    Prerequisites

    • An account and API Key from the MLIT Data Platform.
    • Python 3.10 or higher installed.
    • An MCP-compatible host (e.g., Claude Desktop).

    Installation Steps

    1. Clone the repository

      git clone https://github.com/MLIT-DATA-PLATFORM/mlit-dpf-mcp.git
cd mlit-dpf-mcp

    2. Create and activate a virtual environment

      python -m venv .venv
# Windows:
.venv\Scripts\activate
# macOS/Linux:
source .venv/bin/activate

    3. Install dependencies

      pip install -e .
pip install aiohttp pydantic tenacity python-json-logger mcp python-dotenv

    4. Configure environment variables Create a .env file in the root directory with your credentials:

      MLIT_API_KEY=your_api_key_here
MLIT_BASE_URL=https://data-platform.mlit.go.jp/api/v1/

    5. Configure Claude Desktop Open your claude_desktop_config.json and add the mlit-dpf-mcp configuration. Replace the paths with your actual absolute paths.

      Windows Path: %APPDATA%\Claude\claude_desktop_config.json
      macOS Path: ~/Library/Application Support/Claude/claude_desktop_config.json

      {
  "mcpServers": {
    "mlit-dpf-mcp": {
      "command": "/path/to/mlit-dpf-mcp/.venv/Scripts/python.exe",
      "args": [
        "/path/to/mlit-dpf-mcp/src/server.py"
      ],
      "env": {
        "MLIT_API_KEY": "your_api_key_here",
        "MLIT_BASE_URL": "https://data-platform.mlit.go.jp/api/v1/",
        "PYTHONUNBUFFERED": "1",
        "LOG_LEVEL": "WARNING"
      }
    }
  }
}

    6. Restart Claude Desktop

    {
  "mcpServers": {
    "mlit-dpf-mcp": {
      "command": "/path/to/mlit-dpf-mcp/.venv/Scripts/python.exe",
      "args": [
        "/path/to/mlit-dpf-mcp/src/server.py"
      ],
      "env": {
        "MLIT_API_KEY": "your_api_key_here",
        "MLIT_BASE_URL": "https://data-platform.mlit.go.jp/api/v1/",
        "PYTHONUNBUFFERED": "1",
        "LOG_LEVEL": "WARNING"
      }
    }
  }
}

  3. Environment Variables for MLIT DATA PLATFORM MCP Server

    main

    The following environment variables are required for the server to function. These can be set in a .env file or directly in the claude_desktop_config.json env block.

    • MLIT_API_KEY: Your personal API key obtained from the MLIT Data Platform.
    • MLIT_BASE_URL: The base URL for the MLIT API (default: https://data-platform.mlit.go.jp/api/v1/).
    • PYTHONUNBUFFERED: Set to 1 to ensure logs are sent immediately to the host.
    • LOG_LEVEL: Controls the logging verbosity (e.g., WARNING, INFO, DEBUG).

  5. Handle transient HTTP errors and retries

    main

    The client automatically retries requests that encounter TransientHttpError. This includes:

    • HTTP status codes: 429 (Too Many Requests), 500, 502, 503, 504.
    • Network errors and timeouts.

    Retries use an exponential backoff strategy. The specific parameters (base backoff, max retries) are loaded from the project settings.

  6. Configure debugging via environment variables

    main

    The MLITClient supports several environment variables to control logging and behavior:

    VariableDescription
    MLIT_DEBUG_QUERYSet to 1 to log outgoing GraphQL queries.
    MLIT_DEBUG_RESPSet to 1 to log incoming GraphQL responses.
    MLIT_LOG_BODY_LIMITMaximum characters to log for query/response bodies (default: 4000).
    MLIT_TIMEOUT_SOverrides the default request timeout in seconds.
    MLIT_API_KEY(Implicitly used via config) The API key for authentication.

  7. Configure MLIT MCP Server via Environment Variables

    main

    The MLIT MCP server is configured using environment variables. The MLIT_API_KEY is a required variable. Other settings can be tuned for HTTP reliability, rate limiting, and input constraints.

    Required Environment Variables

    • MLIT_API_KEY: Your API key for the MLIT Data Platform.

    Optional Environment Variables

    • MLIT_BASE_URL: The base URL for the MLIT GraphQL endpoint. Defaults to https://data-platform.mlit.go.jp/api/v1/ if not provided.

    Available Configuration Settings

    SettingTypeDefaultDescription
    timeout_sfloat30.0HTTP request timeout in seconds.
    max_retriesint3Maximum number of retries for failed requests.
    backoff_base_sfloat0.5Base seconds for exponential backoff.
    rpsfloat4.0Requests per second (rate limit).
    max_sizeint500Maximum size per query sample (MLIT recommended upper bound).
    max_distance_mint50000Precautionary limit for geoDistance in meters.

  8. Available MCP Tools in MLIT DATA PLATFORM MCP Server

    main

    The server provides the following tools to the LLM via the MCP interface:

    • search: Search data by keywords (supports sorting and limit).
    • search_by_location_rectangle: Search data intersecting a specified rectangular area.
    • search_by_location_point_distance: Search data intersecting a circular area (point + radius).
    • search_by_attribute: Search by attributes like catalog name, dataset name, prefecture, or municipality.
    • get_data: Retrieve detailed information for a specific data item.
    • get_data_summary: Retrieve basic information (ID, title, etc.) for a data item.
    • get_data_catalog: Retrieve details for a data catalog or dataset.
    • get_data_catalog_summary: Retrieve basic information for a data catalog or dataset.
    • get_file_download_urls: Get download URLs for files (valid for 60 seconds).
    • get_zipfile_download_url: Get a ZIP download URL for multiple files (valid for 60 seconds).
    • get_thumbnail_urls: Get thumbnail image URLs (valid for 60 seconds).
    • get_all_data: Batch retrieve large amounts of data matching criteria.
    • get_count_data: Get the count of data items matching criteria.
    • get_suggest: Get keyword search suggestions.
    • get_prefecture_data: List prefecture names and codes.
    • get_municipality_data: List municipality names and codes.
    • get_mesh: Retrieve data contained within a specified mesh.
    • normalize_codes: Normalize input prefecture or municipality names.

  9. Validation hints and error messages

    main

    The server provides structured error hints when tool arguments are invalid. If a call fails validation, the response will contain a JSON object with the following keys:

    • error: A description of the error.
    • parameter: The specific parameter that caused the issue.
    • provided: The value you sent.
    • expected: The required format or value.
    • examples: A list of valid input examples.

    Common Validation Rules:

    • Search: If using attribute filters (like prefecture_code), a term parameter is required (can be an empty string "").
    • Search by Attribute: Attribute names must include a namespace prefix (e.g., DPF:dataset_id instead of just dataset_id).
    • Get Count Data: If slice_type is set to dataset, you cannot provide a slice_attribute_name.

  10. Troubleshoot Configuration Errors

    main

    If the server fails to start due to a configuration error, ensure that the MLIT_API_KEY environment variable is correctly set. The server uses load_settings() to validate the environment, and if the required key is missing, it will raise a RuntimeError with the following message:

    Config error: set ENV MLIT_API_KEY (and optionally MLIT_BASE_URL).

  12. Get prefecture and municipality lists

    main

    Access standardized lists of administrative divisions.

    • get_prefecture_data: Returns all 47 prefectures. Includes code (numeric), code_as_string (2-digit string), name, hiragana, and romaji.
    • get_municipality_data: Returns lists of municipalities.
      • Filter by pref_codes (array of strings) or muni_codes (array of 6-digit strings).
      • Use the fields parameter to limit the response to specific keys (e.g., ["code_as_string", "name"]) to avoid large payloads.
    {
  "pref_codes": ["13"],
  "fields": ["code_as_string", "prefecture_code", "name"]
}