Metadata-Version: 2.4
Name: nexalware-mcp
Version: 0.1.0
Summary: Nexalware as an MCP server (Python) - lets any MCP-aware agent host (Claude Desktop, Claude Code, Cursor, etc.) discover and call your device control tools automatically.
Author: Nexalware
License-Expression: MIT
Project-URL: Homepage, https://nexalware.com
Project-URL: Documentation, https://docs.nexalware.com/docs/sdk/mcp-server-python
Project-URL: Repository, https://github.com/Darrey1/nexalware-homepage
Project-URL: Issues, https://github.com/Darrey1/nexalware-homepage/issues
Keywords: nexalware,mcp,model-context-protocol,iot,device-control,robotics,claude
Classifier: Programming Language :: Python :: 3
Classifier: Operating System :: OS Independent
Classifier: Typing :: Typed
Classifier: Intended Audience :: Developers
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Topic :: Home Automation
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: mcp>=2.0
Requires-Dist: nexalware>=0.1.0
Dynamic: license-file

# nexalware-mcp

[Nexalware](https://nexalware.com) as an [MCP](https://modelcontextprotocol.io) server, over stdio, for Python. Point any MCP-aware host (Claude Desktop, Claude Code, Cursor, etc.) at it, and your device control tools show up automatically, the host's own model decides when to call them. It's a thin wrapper over the [Python SDK](https://pypi.org/project/nexalware/)'s `make_tools()`, same operations, same permissions, just discoverable instead of hand-coded.

Already on Node? See [`@nexalware/mcp`](https://www.npmjs.com/package/@nexalware/mcp), same tool set. Building your own agent instead of using a pre-built host? Use the SDK directly, in [Python](https://pypi.org/project/nexalware/) or [TypeScript](https://www.npmjs.com/package/@nexalware/sdk). It's one function call away in code you already control, no subprocess or protocol discovery needed.

## Get an API key

Create one on the [dashboard](https://nexalware.com) (API Keys), scoped with a DeviceGrant to only the device(s) this agent should touch. This key ends up sitting in a local config file, least privilege matters more here than for a typical server-side integration.

## Claude Code

```bash
claude mcp add nexalware -e NEXALWARE_API_KEY=nxw_live_sk_your_key_here -- uvx nexalware-mcp
```

## Claude Desktop, or any host using a `mcpServers` config file

Add this block to the host's MCP config (Claude Desktop: Settings -> Developer -> Edit Config):

```json
{
  "mcpServers": {
    "nexalware": {
      "command": "uvx",
      "args": ["nexalware-mcp"],
      "env": {
        "NEXALWARE_API_KEY": "nxw_live_sk_your_key_here"
      }
    }
  }
}
```

Restart the host afterward, tools only load at startup. This uses [`uvx`](https://docs.astral.sh/uv/) to run the package without a separate install step, every launch runs the latest published release. No `uv`? Install it once (`curl -LsSf https://astral.sh/uv/install.sh | sh`), or fall back to a regular install:

```bash
pip install nexalware-mcp
```
```json
{
  "mcpServers": {
    "nexalware": {
      "command": "nexalware-mcp",
      "env": { "NEXALWARE_API_KEY": "nxw_live_sk_your_key_here" }
    }
  }
}
```

## Environment variables

| Variable | Required | Meaning |
|---|---|---|
| `NEXALWARE_API_KEY` | yes | The key from the step above. The server exits immediately with an error if this is missing. |
| `NEXALWARE_API_URL` | no | Override for a self-hosted or staging deployment. Defaults to the production API. |

## Tools

Every tool takes and returns the same shape as its equivalent Python SDK method, a failed call comes back as a normal MCP tool error with the same message the API itself returns, not a crash.

| Tool | What it does | Required params |
|---|---|---|
| `list_devices` | List the devices this key can act on (only what its DeviceGrant(s) cover). Call this first. | none |
| `get_device_commands` | List the commands a device accepts. | `device_id` |
| `send_command` | Send a command to a device. | `device_id`, `cmd` |
| `turn_device_on` | Shorthand for the ON command. | `device_id` |
| `turn_device_off` | Shorthand for the OFF command. | `device_id` |
| `get_device_telemetry` | Read a device's telemetry history. | `device_id` |
| `get_latest_telemetry` | Current state plus latest reading per metric. | `device_id` |
| `list_sub_devices` | List sub-devices behind a master. | `device_id` |
| `get_sub_device` | Read one sub-device's state and capabilities. | `device_id`, `sub_device_id` |
| `get_sub_device_telemetry` | Read one sub-device's telemetry history. | `device_id`, `sub_device_id` |
| `send_sub_device_command` | Send a command to one sub-device behind a master. | `device_id`, `sub_device_id`, `cmd` |
| `list_schedules` | List a device's active schedules. | `device_id` |
| `get_schedule_context` | List the commands available to schedule. | `device_id` |
| `create_schedule` | Create or replace a schedule slot (0-4). | `device_id`, `slot`, `on_ts`, `off_ts` |
| `update_schedule` | Update an existing schedule slot. | `device_id`, `slot` |
| `delete_schedule` | Cancel a schedule slot. | `device_id`, `slot` |
| `get_schedule_history` | List a device's completed/cancelled schedules. | `device_id` |

## What it can't do

Nothing outside the calling key's own DeviceGrant. There's no tool to create a grant, register a device, or manage API keys, those stay dashboard-only, an MCP tool call is only ever as capable as the key you gave it, never able to expand its own access.

`create_schedule`/`update_schedule` fire existing commands from a device's catalog, they can't invent new ones. Defining, editing, or deleting a command definition itself stays a dashboard-only action.

## Links

- [Full docs](https://docs.nexalware.com/docs/sdk/mcp-server-python)
- [SDK Reference (Python)](https://docs.nexalware.com/docs/sdk/sdk-python) / [SDK Reference (TypeScript)](https://docs.nexalware.com/docs/sdk/sdk) - the same operations, called directly from your own code.
- [Device Orchestration](https://docs.nexalware.com/docs/device-orchestration) - what `list_sub_devices`/`send_sub_device_command` actually operate on.

## License

MIT
