SORACOM Server

npm version CI License: MIT

⚠️ EARLY ACCESS: This is an early access project and is provided as-is. There is no guarantee of continued support or maintenance. Use at your own risk.

A Model Context Protocol (MCP) server for interacting with SORACOM APIs.

Quick Start

Prerequisites

• Node.js v22+ (ES modules support)
• SORACOM Auth Key (ID and Token)

Configuration

Add to ~/Library/Application Support/Claude/claude_desktop_config.json:

Authentication Methods

There are two ways to authenticate with SORACOM:

1. Direct environment variables - Set auth key ID and token directly
2. SORACOM CLI profile - Use existing SORACOM CLI profile credentials

Method 1: Using Auth Key Environment Variables

{
  "mcpServers": {
    "soracom": {
      "command": "npx",
      "args": ["@soracom-labs/soracom-mcp-server"],
      "env": {
        "SORACOM_AUTH_KEY_ID": "your-key-id",
        "SORACOM_AUTH_KEY": "your-token",
        "SORACOM_COVERAGE_TYPE": "jp"
      }
    }
  }
}

Required environment variables:

• SORACOM_AUTH_KEY_ID: Your SORACOM authentication key ID
• SORACOM_AUTH_KEY: Your SORACOM authentication key token

Get your authentication keys from:

• Manage Root User Credentials (Japanese)
• AuthKeys (English)

Method 2: Using SORACOM CLI Profile

If you have configured SORACOM CLI profiles, you can use them instead:

{
  "mcpServers": {
    "soracom": {
      "command": "npx",
      "args": ["@soracom-labs/soracom-mcp-server"],
      "env": {
        "SORACOM_PROFILE": "production"
      }
    }
  }
}

Required environment variable:

• SORACOM_PROFILE: SORACOM CLI profile name
  • Credentials are loaded from ~/.soracom/<profile>.json
  • Profile file should contain authKeyId and authKey fields
  • See SORACOM CLI Basic Usage for profile configuration details

Common Environment Variable (Both Methods)

• SORACOM_COVERAGE_TYPE: API coverage region
  • "jp" for Japan coverage
  • "g" for Global coverage
  • Priority: Environment variable > Profile coverageType > Default "jp"

That's it! No installation needed - npx will download and run the server automatically.

Security Recommendation

For enhanced security, we recommend creating a SAM (SORACOM Access Management) user with permissions limited to only the necessary API operations, rather than using your root user credentials. Generate the AuthKey ID and Token from this SAM user for use with this MCP server.

Using with Docker

You can also run the MCP server using Docker. Build the image with the following command:

docker build -t soracom-mcp-server:latest .

Settings are like below:

{
  "mcpServers": {
    "soracom": {
      "command": "docker",
      "args": [
        "run",
        "--rm",
        "-i",
        "-e",
        "SORACOM_AUTH_KEY_ID",
        "-e",
        "SORACOM_AUTH_KEY",
        "soracom-mcp-server:latest"
      ],
      "env": {
        "SORACOM_AUTH_KEY_ID": "your-key-id",
        "SORACOM_AUTH_KEY": "your-token",
        "SORACOM_COVERAGE_TYPE": "jp"
      }
    }
  }
}

Usage

Command Naming Convention

All commands follow the pattern Category_operationId where:

• Category is the API category (e.g., Sim, Billing, Stats)
• operationId is the operation name from the SORACOM API

Examples:

• Sim_getSim - Get SIM information
• Billing_getLatestBilling - Get latest billing information
• Query_searchSims - Search for SIMs

Example Commands in Claude Desktop

Get information for SIM ID "8981100000000000000" using the Sim_getSim command
List all active SIMs with limit 10 using the Sim_listSims command
Show billing for current month using the Billing_getLatestBilling command
Find SIMs with name containing "production" using the Query_searchSims command

Coverage Selection

• Default: Set SORACOM_COVERAGE_TYPE to "jp" or "g" in config
• Per-command: Each command accepts optional coverage parameter

Available Tools

See Available Tools Documentation for the complete list of supported commands.

Development

See development guides for setup and workflow:

• Local Development Guide - Setup and workflow
• Claude Desktop Development - Testing with Claude Desktop
• Architecture Documentation - Project structure and design

License

MIT