coppeliasim-mcp

実行中のCoppeliaSim 4.10シミュレーションをClaude Code（または任意のMCPクライアント）から操作できるMCPサーバー：シーンの構築、オブジェクトの移動、ジョイントと近接センサーの作成、シミュレーションの実行、センサーの読み取りが可能です。

任意のLuaコードの実行は意図的に公開していません。 これが他のCoppeliaSim MCPサーバーとの主な違いです。セキュリティを参照してください。

ツール名はデフォルトでスペイン語で、英語とポルトガル語のエイリアスもオプションで利用できます — ツール名の言語を参照してください。

Coppelia Robotics AGとは提携・承認・保守関係にありません。 CoppeliaSimはCoppelia Robotics AGの商標です。これは独立したサードパーティ製の統合です。シミュレーター自体についてはcoppeliarobotics.comをご覧ください。

要件

• ZMQ remote APIアドオンが有効なCoppeliaSim 4.10が実行中であること。デフォルトで有効になっており、ポート23000で待ち受けます。

• Python 3.10以降。

Related MCP server: Robonine MCP Server

インストール

# Recommended: no clone, no virtualenv to manage
uvx coppeliasim-mcp

# Or install it
pip install coppeliasim-mcp

Claude Codeに登録します：

claude mcp add coppelia -- uvx coppeliasim-mcp

または、JSON設定を読み取る任意のMCPクライアントの場合：

{
  "mcpServers": {
    "coppelia": {
      "command": "uvx",
      "args": ["coppeliasim-mcp"]
    }
  }
}

設定

すべての設定はオプションの環境変数です。作業ディレクトリの.envファイルにも配置できます — .env.exampleを参照してください。

ツール

シミュレーション制御 — iniciar_simulacion、detener_simulacion、pausar_simulacion、estado_simulacion、tiempo_simulacion

シーン — cargar_escena、cerrar_escena

オブジェクト — listar_objetos、obtener_posicion、fijar_posicion、obtener_orientacion、fijar_orientacion、crear_primitiva、eliminar_objeto、emparentar_objeto、fijar_detectable

ジョイント — obtener_posicion_junta、fijar_objetivo_junta、fijar_velocidad_junta、obtener_fuerza_junta

近接センサー — crear_sensor_proximidad、leer_sensor_proximidad、comprobar_sensor_proximidad

ツール名の言語

ツールはスペイン語で定義されています（crear_primitiva、leer_sensor_proximidadなど）。COPPELIA_IDIOMASを設定すると、同じ関数を指す英語とポルトガル語のエイリアスが登録されます — ロジックの重複はなく、カタログに名前が増えるだけです。

カタログは毎回のリクエストでモデルに送信されるため、エイリアスはデフォルトでオフになっています。オンにする前に知っておくべきこと：モデルは別の言語で理解するために翻訳された名前を必要としません。ツール名は識別子であり、ユーザー向けのテキストではありません — 「move the cube forward」や「mova o cubo para frente」と頼めば、どちらにせよfijar_posicionに到達します。エイリアスは、カタログをひと目で読みたい場合や、プロンプトでツールを明示的に指定したい場合に役立ちます。

例

examples/carrito_diferencial.pyは、障害物回避付きの完全な差動駆動ロボットを構築し、実際に機能するかどうかを測定します。examples/README.mdを参照してください。

セキュリティ

CoppeliaSimのLua環境はosとioにアクセスできます。任意のLuaを実行するツールは、プロンプトインジェクション — 例えば、モデルが検査するよう求められたサードパーティ製の.tttシーンに埋め込まれたテキスト — を、あなたのマシンでのコマンド実行に変えてしまいます。このサーバーにはそのようなツールは意図的にありません。

残りの攻撃面も意図的に狭くしています：

• cargar_escenaは、COPPELIA_DIRECTORIO_ESCENASと比較する前にパスを解決します（Path.resolve(strict=True)）。そのため、../..やシンボリックリンクで逃げることはできず、シーン拡張子のみを受け付けます。

• COPPELIA_MODO_LECTURA=1は、すべての変更系ツールを一度に無効にします。

• シーンディレクトリのデフォルトはホームではなく作業ディレクトリです。

デバッグ時間を節約するメモ

CoppeliaSim APIで間違えやすい点で、ツールが直接表面化するもの：

• leer_sensor_proximidadは検出しません。 シミュレーターの最後のセンサーパスの結果を返すため、シミュレーション停止中は常に何も報告しません。オンデマンドで検出するにはcomprobar_sensor_proximidadを使用してください。

• オブジェクトは検出可能としてマークされる必要があります。近接センサーに認識されるためには。それがfijar_detectableの目的であり、センサーが「機能しない」通常の原因です。

• 水平に向いた広いコーンは、障害物の前に床を検出します。 半開角a、センサーの高さhの場合、床は*h / tan(a)*でコーンに入ります。それがセンサー範囲内にある場合、センサーは地面を報告します。

• 再ペアレント化は兄弟パスの番号を振り直します。 /Cylinder[1]をシャーシにぶら下げた後、/Cylinder[3]が/Cylinder[1]になる可能性があります。連続するemparentar_objeto呼び出しの間でオブジェクトを再リストするか、事前にハンドルを解決してください。

• ペアレント化は2つの動的シェイプを剛体的に結合しません。 非静的シェイプは、ジョイントやフォースセンサーで拘束されない限り落下します。

リリース

公開はタグのプッシュ時に、.github/workflows/publicar.ymlを通じて実行されます：

# bump version in pyproject.toml first, then
git tag v0.1.0 && git push --tags

ワークフローは、タグとpyproject.tomlのバージョンが一致しない場合に公開を拒否し、Python 3.10と3.13でビルドしたホイールをインストールし、scripts/prueba_humo.py — MCPハンドシェイクと、シミュレーターがない状態での呼び出しがハングせずに応答するかのチェック — を実行してからアップロードします。PyPIのバージョンは上書きや再利用ができないため、CIでの失敗はバージョン番号を消費するよりはるかに安価です。

PyPIへの認証はTrusted Publishing（OIDC）を通じて行われるため、リポジトリのシークレットにトークンは保存されません。

ライセンス

MIT — LICENSEを参照してください。

MITライセンスはこのサーバーのみを対象としています。CoppeliaSim自体はCoppelia Robotics AGによって別途ライセンスされており、このパッケージはその一部を含んだり再配布したりしません — 自分でインストールしてライセンスするシミュレーターと通信するだけです。

coppeliasim-mcp（スペイン語）

Claude Codeまたは任意のMCPクライアントからCoppeliaSim 4.10シミュレーションを操作するためのMCPサーバー：シーンの構築、オブジェクトの移動、ジョイントと近接センサーの作成、シミュレーションの実行、センサーの読み取り。

任意のLua実行は意図的に公開していません。 これが他のCoppeliaSim MCPとの主な違いです。CoppeliaSimのLuaはosとioにアクセスできるため、そのようなツールはプロンプトインジェクション — 例えば、サードパーティ製の.tttシーン内のテキスト — を、あなたのマシンでのコマンド実行に変えてしまいます。

Coppelia Robotics AGとは提携・承認・保守関係にありません。 CoppeliaSimはCoppelia Robotics AGの商標です。これは独立したサードパーティ製の統合です。シミュレーターについてはcoppeliarobotics.comをご覧ください。

要件

• ZMQ remote APIアドオンが有効なCoppeliaSim 4.10が開いていること。デフォルトで有効で、ポート23000で待ち受けます。

• Python 3.10以降。

インストール

uvx coppeliasim-mcp                              # recomendado
pip install coppeliasim-mcp                      # o instalado
claude mcp add coppelia -- uvx coppeliasim-mcp   # registrar en Claude Code

設定

環境変数、すべてオプションです。作業ディレクトリの.envにも配置できます — .env.exampleを参照してください。

ツール名の言語

ツールはスペイン語で定義されています。COPPELIA_IDIOMASは同じ関数に対する英語とポルトガル語のエイリアスを登録します：ロジックの重複はなく、名前が増えるだけです。

カタログは毎回のリクエストでモデルに送信されるため、エイリアスはオフになっています。オンにする前に知っておくべきこと：モデルは別の言語で理解するために翻訳された名前を必要としません。ツール名は識別子であり、ユーザー向けのテキストではありません — 「move the cube forward」や「mova o cubo para frente」と頼めば、fijar_posicionを同じように使います。エイリアスは、カタログをひと目で読みたい場合や、ツールを明示的に指定したい場合に役立ちます。

例

examples/carrito_diferencial.pyは、障害物回避付きの完全な差動駆動カートを構築し、実際に機能するかどうかを測定します。examples/README.mdを参照してください。

デバッグ時間を節約するメモ

• leer_sensor_proximidadは検出しません。 シミュレーターの最後のスキャンの結果を返すため、シミュレーション停止中は常に何もないと報告します。その場で検出するにはcomprobar_sensor_proximidadを使用してください。

• オブジェクトは検出可能としてマークされる必要があります。近接センサーに認識されるためには。それがfijar_detectableの目的であり、「機能しない」センサーの通常の原因です。

• 水平に向いた広いコーンは、障害物の前に床を検出します。 半開角a、センサーの高さhの場合、床は*h / tan(a)*でコーンに入ります。それが範囲内にある場合、センサーは床を報告します。

• ペアレント化は兄弟パスの番号を振り直します。 /Cylinder[1]をシャーシにぶら下げた後、/Cylinder[3]が/Cylinder[1]になる可能性があります。呼び出しの間でオブジェクトを再リストするか、階層を触る前にハンドルを解決してください。

• ペアレント化は2つの動的ボディを剛体的に結合しません。 非静的シェイプは、ジョイントやフォースセンサーで拘束されない限り落下します。

ライセンス

MIT — LICENSEを参照してください。

MITライセンスはこのサーバーのみを対象としています。CoppeliaSimはCoppelia Robotics AGと別途ライセンスされており、このパッケージはその一部を含んだり再配布したりしません — 自分でインストールしてライセンスするシミュレーターと通信するだけです。