SORACOM Data

This MCP server lets you access and analyze SORACOM Harvest Data, Harvest Files, SoraCam devices and media, plus SIM statistics through a unified Model Context Protocol interface. It authenticates with your SAM user credentials and exposes practical data retrieval and management capabilities for data-driven workflows.

How to use

You connect to this MCP server from your MCP client and choose a mode to fetch the data you need. Harvest mode collects sensor data and file storage information, Soracam mode provides camera data and media, and Stats mode delivers SIM information and usage statistics. You can run multiple MCP server configurations to match your deployment needs. Use environment variables to securely provide your authentication keys.

To start, ensure you have an MCP client installed and that you have your authentication keys ready. Create one or more MCP server configurations as shown in the examples. Each configuration defines how to start a local MCP runner and which mode it should operate in. The runner will connect to SORACOM APIs using your auth keys and will expose the available endpoints through the MCP interface.

How to install

Prerequisites you need before installation:

• Node.js (for npm/npx usage) or a compatible JavaScript runtime
• A working internet connection to fetch MCP runtimes
• Access to your SAM authentication keys (authKeyId and authKey)

Install one of the MCP runners and start harvesting data with the following concrete commands.

# Install the MCP runner from the source and run Harvest mode (direct npm/uv usage example)
uv tool install git+https://github.com/leaveanest/alt-soracom-data-reader-mcp.git
soracom-data-mcp --mode harvest

Configuration and security

You must provide your SORACOM SAM authentication keys as environment variables when starting the MCP runner. The required keys are SORACOM_AUTH_KEY_ID and SORACOM_AUTH_KEY. Optionally, you can set the coverage region with SORACOM_COVERAGE (default is jp). These values are used by all modes to authenticate requests to Harvest Data, Harvest Files, SoraCam, and subscriber statistics.

Example environment setup before starting the MCP runner:

export SORACOM_AUTH_KEY_ID="keyId-xxx"  # required
export SORACOM_AUTH_KEY="secret-xxx"    # required
export SORACOM_COVERAGE="jp"            # optional (default: jp)

MCP configuration examples

Multiple ways to run the Harvest mode are supported. The following configurations are explicit examples you can place in your MCP setup file. Each entry starts the same runner with the harvest mode and provides the required environment variables.

{
  "mcpServers": {
    "soracom-harvest-uv": {
      "command": "soracom-data-mcp",
      "args": ["--mode", "harvest"],
      "env": {
        "SORACOM_AUTH_KEY_ID": "keyId-xxx",
        "SORACOM_AUTH_KEY": "secret-xxx"
      }
    }
  }
}

Additional MCP runner variants

If you prefer alternative ways to run the Harvest mode, you can use UVX to run directly from a Git source, or run locally with UV. The following variants are explicitly supported.

{
  "mcpServers": {
    "soracom-harvest-uvx": {
      "command": "uvx",
      "args": [
        "--from",
        "git+https://github.com/leaveanest/alt-soracom-data-reader-mcp.git",
        "soracom-data-mcp",
        "--mode",
        "harvest"
      ],
      "env": {
        "SORACOM_AUTH_KEY_ID": "keyId-xxx",
        "SORACOM_AUTH_KEY": "secret-xxx"
      }
    },
    "soracom-harvest_local": {
      "command": "uv",
      "args": ["run", "soracom-data-mcp", "--mode", "harvest"],
      "env": {
        "SORACOM_AUTH_KEY_ID": "keyId-xxx",
        "SORACOM_AUTH_KEY": "secret-xxx"
      }
    }
  }
}

Available tools

Harvest Data access

Retrieve Harvest Data for a specific IMSI or resource type to analyze sensor data.

Harvest Files access

List and download files from Harvest Files, including storage usage info.

SoraCam devices management

Fetch the list of SoraCam devices and their details.

SoraCam videos export

Start video exports and monitor export status for Soracam devices.

SoraCam video retrieval

Obtain video listings, static images, and streaming URLs for Soracam devices.

SoraCam events

List and inspect events detected by Soracam devices.

Subscribers and stats

Query SIM information and usage statistics, including data usage.