Tokyo Metro MCP Server

An MCP (Model Context Protocol) server that provides access to Tokyo Metro's Open Data API.

Features

• tokyo_metro_query: Make POST requests to any Tokyo Metro API endpoint with filtering capabilities
• get_sample_covid_data: Get COVID-19 data from Tokyo with date range filtering

Installation

npm install
npm run build

Usage

The server supports POST requests to Tokyo Metro API endpoints with advanced filtering:

Tools Available

1. tokyo_metro_query

Query any Tokyo Metro API endpoint with optional filtering.

Parameters:

• api_url (required): The Tokyo Metro API endpoint URL
• columns (optional): Array of specific columns to retrieve
• limit (optional): Maximum number of records (default: 100)
• search_conditions (optional): Object with filtering conditions

Example:

{
  "api_url": "https://service.api.metro.tokyo.lg.jp/api/t000003d0000000093-85208d055a15cce25cc6cee785d52d75-0/json",
  "columns": ["column1", "column2"],
  "limit": 50,
  "search_conditions": {
    "condition_relationship": "and",
    "date_filters": [
      {
        "column": "公表_年月日",
        "operator": "ge", 
        "value": "2021/1/1"
      }
    ]
  }
}

2. get_sample_covid_data

Get COVID-19 data from Tokyo Metro's dataset.

Parameters:

• start_date (optional): Start date in YYYY/M/D format
• end_date (optional): End date in YYYY/M/D format
• limit (optional): Maximum records (default: 365)

API Response Format

The Tokyo Metro API returns responses in this format:

{
  "total": 365,
  "subtotal": 365, 
  "limit": 365,
  "offset": null,
  "metadata": {
    "apiId": "string",
    "title": "string",
    "datasetId": "string",
    "datasetTitle": "string",
    "datasetDesc": "string",
    "dataTitle": "string", 
    "dataDesc": "string",
    "sheetname": "string",
    "version": "string",
    "created": "string",
    "updated": "string"
  },
  "hits": [
    {
      "row": 1,
      "column1": "value1",
      "column2": "value2"
    }
  ]
}

Filter Operators

Date Filters

• eq: Equal to
• ne: Not equal to
• gt: Greater than
• ge: Greater than or equal to
• lt: Less than
• le: Less than or equal to

Text Filters

• eq: Exact match
• ne: Not equal to
• partial: Partial/contains match

Running the Server

For Mastra Integration (HTTP Mode)

npm run build
npm run start:http

Or for development:

npm run dev:http

Server runs on port 3001 by default (configurable via PORT env var).

For MCP stdio mode

npm start

Or for development:

npm run dev

HTTP API Endpoints (Mastra Integration)

When running in HTTP mode, the following endpoints are available:

• GET /health - Health check
• GET /tools - List available MCP tools
• POST /tools/:toolName - Execute specific MCP tool
• POST /tokyo-metro/query - Direct Tokyo Metro API query
• GET /tokyo-metro/covid - Get COVID-19 data with query parameters

Example HTTP Usage

# Health check
curl http://localhost:3001/health

# List tools
curl http://localhost:3001/tools

# Query Tokyo Metro API
curl -X POST http://localhost:3001/tokyo-metro/query \
  -H "Content-Type: application/json" \
  -d '{
    "api_url": "https://service.api.metro.tokyo.lg.jp/api/your-endpoint/json",
    "limit": 100
  }'

# Get COVID data
curl "http://localhost:3001/tokyo-metro/covid?start_date=2021/1/1&end_date=2021/12/31&limit=100"

Environment Configuration

Copy .env.example to .env and configure:

cp .env.example .env

• PORT: HTTP server port (default: 3001)
• MODE: Server mode - "http" for HTTP server, "stdio" for MCP mode