OpenSolar MCP

OpenSolar MCP は、ドキュメント化された OpenSolar API 向けの Model Context Protocol サーバーです。ご自身のマシンまたはインフラストラクチャ上で動作し、ご自身の OpenSolar 認証情報を使用して、プロジェクト、連絡先、システム、ファイル、商用設定、Teams の共有に対応する厳選されたツール群を AI エージェントに提供します。

flowchart LR
    client["MCP client<br/>Claude · Cursor · VS Code · Codex"]
    server["OpenSolar MCP<br/>runs where you run it"]
    api[("OpenSolar API<br/>api.opensolar.com")]
    client -- "stdio or Streamable HTTP" --> server
    server -- "HTTPS with your bearer token" --> api

重要

このプロジェクトは OpenSolar Pty Ltd と提携、承認、運営されているものではありません。公開されているドキュメント化済みの OpenSolar API のみを呼び出し、共有またはホスト型の OpenSolar サービスを運営することはありません。

主な特長

• エージェント向けに厳選。 デフォルトの 31 ツールのプロファイルで、日常的な作業をカバーします。登録済みの 75 ツールすべてを、設定ひとつで利用できます。
• 単なるエンドポイントではなく、意味のある操作。 プロジェクトと連絡先の検索、運用スナップショット、名前によるステージ変更、システムの並列比較、設計の概要、読み取り専用の共有事前確認に対応します。
• 設計段階から慎重。 検索では一致結果が unique、ambiguous、incomplete のいずれかとして報告され、エージェントには推測しないよう指示されます。書き込みは自動再試行されず、読み取り専用モードではすべての変更操作が無効になります。
• OpenSolar のドキュメントに忠実。 すべてのツールは公式 API ドキュメント、または記録された実環境での検証に基づいており、リクエスト本文が確定している場合にのみ書き込み操作を公開します。各ツールの根拠はAPI コントラクトマトリクスに記載されています。
• クリーンなモデルコンテキスト。 公開済みスキーマを備えた構造化出力を提供します。認証情報、署名付き URL、設計データ、その他の生データや機密フィールドは、モデルに届く前に取り除かれます。
• 最新の MCP に対応。 2026-07-28 仕様に対応した公式 MCP TypeScript SDK v2 を基盤とし、以前のプロトコルバージョンを使用するクライアント向けのフォールバックも備えています。stdio とステートレスな Streamable HTTP をサポートし、すべてのツールでタイトル、出力スキーマ、動作アノテーションを宣言します。

質問できること

クイックスタート

要件

• Node.js 24 以降
• API Access が有効になっている OpenSolar 組織
• OpenSolar 組織 ID と ベアラートークン
• get_proposal_data または get_project_design を使用する場合のみ、Raw Data API Access

ヒント

OpenSolar の標準ユーザートークンは 7 日後に有効期限が切れます。長期間運用する場合は、API 作業専用の OpenSolar ユーザーを作成し、マシンユーザーに設定してください。マシンユーザーのトークンには有効期限がありません。このサーバーが代わりにこの設定を変更することはありません。

1. 利用できるツールを確認します（認証情報は不要です）。

npx -y @alignco/opensolar-mcp --list-tools

2. 設定とトークンを確認します。

OPENSOLAR_API_TOKEN=your_token OPENSOLAR_ORG_ID=12345 \
  npx -y @alignco/opensolar-mcp --check

--check は組織の情報を 1 回読み取ります。OpenSolar に接続せず設定を検証するには、--no-probe を追加してください。

3. 以下のいずれかの方法で MCP クライアントに追加します。

MCP クライアントを接続する

すべてのクライアントで必要な設定は、OPENSOLAR_API_TOKEN と OPENSOLAR_ORG_ID の 2 つです。以下の your_token と 12345 を、ご自身の値に置き換えてください。

claude mcp add opensolar \
  -e OPENSOLAR_API_TOKEN=your_token \
  -e OPENSOLAR_ORG_ID=12345 \
  -- npx -y @alignco/opensolar-mcp

{
  "mcpServers": {
    "opensolar": {
      "command": "npx",
      "args": ["-y", "@alignco/opensolar-mcp"],
      "env": {
        "OPENSOLAR_API_TOKEN": "your_token",
        "OPENSOLAR_ORG_ID": "12345"
      }
    }
  }
}

{
  "mcpServers": {
    "opensolar": {
      "command": "npx",
      "args": ["-y", "@alignco/opensolar-mcp"],
      "env": {
        "OPENSOLAR_API_TOKEN": "your_token",
        "OPENSOLAR_ORG_ID": "12345"
      }
    }
  }
}

{
  "inputs": [
    {
      "type": "promptString",
      "id": "opensolar_api_token",
      "description": "OpenSolar API token",
      "password": true
    },
    {
      "type": "promptString",
      "id": "opensolar_org_id",
      "description": "OpenSolar organisation ID"
    }
  ],
  "servers": {
    "opensolar": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@alignco/opensolar-mcp"],
      "env": {
        "OPENSOLAR_API_TOKEN": "${input:opensolar_api_token}",
        "OPENSOLAR_ORG_ID": "${input:opensolar_org_id}"
      }
    }
  }
}

{
  "mcpServers": {
    "opensolar": {
      "command": "npx",
      "args": ["-y", "@alignco/opensolar-mcp"],
      "env": {
        "OPENSOLAR_API_TOKEN": "your_token",
        "OPENSOLAR_ORG_ID": "12345"
      }
    }
  }
}

[mcp_servers.opensolar]
command = "npx"
args = ["-y", "@alignco/opensolar-mcp"]
env = { OPENSOLAR_API_TOKEN = "your_token", OPENSOLAR_ORG_ID = "12345" }

{
  "mcpServers": {
    "opensolar": {
      "command": "npx",
      "args": ["-y", "@alignco/opensolar-mcp"],
      "env": {
        "OPENSOLAR_API_TOKEN": "your_token",
        "OPENSOLAR_ORG_ID": "12345"
      }
    }
  }
}

npm install -g @alignco/opensolar-mcp
opensolar-mcp --version

ヒント

使い方に慣れるまでは、env ブロックに OPENSOLAR_READ_ONLY=1 を設定して始めてください。これにより、OpenSolar のデータを変更できるすべてのツールが無効になります。

ツール

プロファイル

プロファイルは、厳選された操作環境です。ツールセットは、直接選択できる機能領域です。読み取り専用モードとアクセスプランのフィルターは、どちらにも適用されます。

--list-tools を実行すると、設定によって有効になる操作環境が常に正確に表示されます。

npx -y @alignco/opensolar-mcp --list-tools
OPENSOLAR_PROFILE=full npx -y @alignco/opensolar-mcp --list-tools
OPENSOLAR_TOOLSETS=webhooks npx -y @alignco/opensolar-mcp --list-tools

デフォルトの agent ツール

✏️ は OpenSolar のデータを変更するツールを示します。🔒 は Raw Data API Access が必要なツールを示します。

ドキュメントにリクエスト本文が明記されていないため、一部の OpenSolar 操作は意図的に公開していません。たとえば、価格体系、支払いオプション、原価、コンポーネントの有効化の作成や、ワークフローまたは組織の更新などです。現在の実装に一覧があります。

設定

OPENSOLAR_TOOLSETS はプロファイルより優先されます。その後に OPENSOLAR_READ_ONLY と OPENSOLAR_PLAN が適用されます。コメント付きテンプレートについては .env.example を参照してください。サーバー自体は .env ファイルを読み込みません。

ローカルファイルのアップロード

create_private_file はサーバーを実行しているマシン上のファイルをアップロードするため、デフォルトでは無効です。有効にするには、ディレクトリを指定します。

export OPENSOLAR_UPLOAD_ROOT=/absolute/path/to/uploads

相対パスはそのディレクトリ内で解決されます。絶対パスとシンボリックリンクは、実際のパスがそのディレクトリ内にとどまる場合にのみ使用できます。モデルがファイルのバイトデータを送信することはありません。

get_private_file と get_system_image によるダウンロードは 10 MB に制限されます。テキストコンテンツはモデルに返されます。画像やその他のバイナリファイルは JSON にコピーされず、MCP の画像またはリソースコンテンツとして返されます。

リモートデプロイ

サーバーは、ネットワーク経由で接続するクライアント向けに、ステートレスな Streamable HTTP も使用できます。

OPENSOLAR_API_TOKEN=your_token OPENSOLAR_ORG_ID=12345 \
  npx -y @alignco/opensolar-mcp --http

ループバックアドレスでは、Authorization: Bearer <token> ヘッダーが優先され、OPENSOLAR_API_TOKEN 変数はローカルのフォールバックとして使用されます。

localhost を超えて公開する

ループバック以外にバインドする場合、すべての MCP リクエストで OpenSolar のベアラートークンが必須です。OPENSOLAR_API_TOKEN 変数はフォールバックとして無視され、不正な形式の Authorization ヘッダーは拒否されます。

export OPENSOLAR_ORG_ID=12345
export MCP_HTTP_HOST=0.0.0.0
export MCP_HTTP_ALLOWED_HOSTS=mcp.example.com
npx -y @alignco/opensolar-mcp --http

たとえば、リクエストヘッダーにトークンを指定してクライアントを接続します。

claude mcp add --transport http opensolar https://mcp.example.com/mcp \
  --header "Authorization: Bearer your_token"

警告

組み込みサーバーは平文の HTTP を使用します。ネットワーク上でトークンを送信する前に、TLS を終端するリバースプロキシまたはプラットフォームの背後に配置してください。MCP_HTTP_ALLOWED_HOSTS と MCP_HTTP_ALLOWED_ORIGINS は、DNS リバインディングやクロスサイトのブラウザーリクエストを防ぐための設定であり、認証機能ではありません。

Docker

このイメージは、非特権ユーザーとして HTTP トランスポートを実行し、ヘルスチェックを備えています。

docker pull ghcr.io/align-software-company/opensolar-mcp:latest
docker run --rm \
  -e OPENSOLAR_ORG_ID=12345 \
  -p 127.0.0.1:3000:3000 \
  ghcr.io/align-software-company/opensolar-mcp:latest

このリポジトリをクローンした場所からビルドするには、次のようにします。

docker build -t opensolar-mcp .
docker run --rm \
  -e OPENSOLAR_ORG_ID=12345 \
  -p 127.0.0.1:3000:3000 \
  opensolar-mcp

コンテナー内では、サーバーは 0.0.0.0 にバインドされるため、クライアントはすべてのリクエストで Authorization: Bearer <token> を送信する必要があります。このイメージでは、Host 値として localhost と 127.0.0.1 が許可されています。それ以外の場合は、MCP_HTTP_ALLOWED_HOSTS に公開ホスト名を設定してください。

セキュリティモデル

• テレメトリーはありません。 サーバーは分析データや使用状況データを送信しません。外部へのリクエストは、OpenSolar API と、OpenSolar から返されるファイルおよび画像の URL に限られます。
• 認証情報はご自身のプロセス内に留まります。 トークンは環境変数またはクライアントの設定内に留まります。何も永続化されず、このプロジェクトはホスト型サービスを実行しません。
• 書き込みは明示的に行われます。 データを変更するツールには MCP の readOnlyHint: false アノテーションが付与され、破壊的なツールには destructiveHint: true が付与されます。また、いずれも自動的に再試行されません。OPENSOLAR_READ_ONLY=1 を設定すると、これらのツールはすべて無効になります。
• 推測は行いません。 検索で対象が確定するのは、resolution: unique が返された場合、または完全なスキャンでメールアドレスもしくは電話番号が完全一致する候補が 1 件だけの場合に identifier_match_id が返された場合に限られます。サーバーは書き込みを再試行せず、隠れた一括書き込み機能も公開しません。
• 出力は最小限です。 署名付きダウンロード URL、連携シークレット、Webhook シークレット、個人を特定する情報、未加工の設計データは、マスキングまたは省略されます。
• 処理量には上限があります。 検索、ダウンロード、Raw Data の展開にはすべて固定の上限があります。通常の読み取りのみ再試行され、HTTP 429 の場合に限り、最大 3 回まで再試行されます。
• HTTP モードでは OpenSolar トークンがそのまま転送されます。 クライアントが送信するベアラートークン自体が OpenSolar トークンであり、そのまま OpenSolar に転送されます。これは MCP OAuth トークンではありません。複数人で 1 つのデプロイメントを共有する場合は、認証ゲートウェイを前段に配置してください。

脆弱性は非公開で報告してください。詳細は SECURITY.md をご覧ください。

互換性

成功した構造化ツールの結果には、同じペイロードを簡潔な JSON テキストとしてシリアライズしたものも含まれます。そのため、structuredContent を転送しないクライアントでも、構造化された結果全体をモデルに渡すことができます。

トラブルシューティング

ログは JSON Lines 形式で stderr に出力されるため、stdout は MCP プロトコル用にクリーンな状態に保たれます。

開発

git clone https://github.com/Align-Software-Company/opensolar-mcp.git
cd opensolar-mcp
corepack enable
pnpm install --frozen-lockfile
pnpm check:all      # repository hygiene, registry metadata, lint, typecheck, offline tests
pnpm build
pnpm test:docker    # build and smoke-test the Docker image

通常のテストスイートはオフラインで実行されます。ライブ統合テストは .env.local を読み込み、デフォルトでは読み取り専用で実行されます。書き込みには OPENSOLAR_INTEGRATION_WRITES=1 と専用のフィクスチャレコードが必要です。

pnpm test:integration
OPENSOLAR_INTEGRATION_WRITES=1 pnpm test:integration

プルリクエストを作成する前に、CONTRIBUTING.md をお読みください。特に OpenSolar API の根拠に関するルールを確認してください。

ドキュメント

貢献

貢献を歓迎します。CONTRIBUTING.md と行動規範をご覧ください。セキュリティ上の問題については、イシューを作成せず、SECURITY.md に従ってください。

ライセンス

MIT © 2026 Align Software Company.

OpenSolar は OpenSolar Pty Ltd の商標です。このプロジェクトは独立したものであり、OpenSolar の承認を受けていません。