Documentation: https://shellsmith.pages.dev

Shellsmith is a Python SDK for managing Asset Administration Shells (AAS) via the Eclipse BaSyx REST API.

Installation

pip install shellsmith

For CLI and MCP server support, install with optional dependencies:

pip install shellsmith[cli,mcp]

Requires: Python 3.10+

Python API Usage

You can also use shellsmith as a Python client library to interact with the BaSyx Environment REST API.

import shellsmith

# Fetch all AAS Shells
shells = shellsmith.get_shells()

# Fetch a specific Submodel
submodel = shellsmith.get_submodel("https://example.com/submodels/my-submodel")

# Read and update a Submodel Element's value
value = shellsmith.get_submodel_element_value(submodel["id"], "temperature")
shellsmith.patch_submodel_element_value(submodel["id"], "temperature", "42.0")

ℹ️ shell_id and submodel_id are automatically base64-encoded unless you pass encode=False.

➡️ Full Python API reference: shellsmith.pages.dev/api

CLI Usage

Shellsmith provides a powerful command-line interface:

aas --help

Command	Description
info	Display the current Shell tree and identify issues.
upload	Upload a single AAS file or all AAS files from a folder.
nuke	☢️ Delete all Shells and Submodels (irrevocable).
encode	Encode a value (e.g. Shell ID) to Base64.
decode	Decode a Base64-encoded value.
get	Get Shells, Submodels, and Submodel Elements.
delete	Delete Shells, Submodels, or Submodel Elements.
update	Update Shells, Submodels, or Submodel Elements.
create	Create new Shells, Submodels, or Submodel Elements.

ℹ️ Run aas <command> --help to view subcommands and options.

➡️ Full CLI reference: shellsmith.pages.dev/cli

MCP Integration

Shellsmith provides a Model Context Protocol (MCP) server that enables AI assistants to interact with Asset Administration Shells. The server exposes 25+ tools for comprehensive AAS management through a standardized interface.

Configure with Claude Desktop or other MCP clients to get AI-powered AAS operations.

➡️ Full MCP reference: shellsmith.pages.dev/mcp

Configuration

The default AAS environment host is:

http://localhost:8081

You can override it in several ways:

• Set the environment variable:

  SHELLSMITH_BASYX_ENV_HOST=https://your-host:1234

• Create a .env file in your project with:

  SHELLSMITH_BASYX_ENV_HOST=https://your-host:1234

• Use the --host option with any CLI command:

  aas get shells --host https://your-host:1234

• Pass the host parameter in any shellsmith Python function:

  shellsmith.get_shells(host="https://your-host:1234")

ℹ️ The --host CLI flag and host= Python argument take precedence over environment variables and .env.

Contributing

We welcome contributions!

See the Contributing Guide for setup, testing, and coding standards.

Resources

• https://github.com/eclipse-basyx/basyx-java-server-sdk
• https://github.com/admin-shell-io/aas-specs-api
• https://app.swaggerhub.com/apis/Plattform_i40/Entire-API-Collection