# Logitech Sync MCP

[English](README.md) | [Français](README.fr.md)

[![CI](https://github.com/bouchecousue/logitech-sync-mcp/actions/workflows/ci.yml/badge.svg)](https://github.com/bouchecousue/logitech-sync-mcp/actions/workflows/ci.yml)
[![Python 3.12+](https://img.shields.io/badge/Python-3.12%2B-3776AB.svg)](https://www.python.org/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)

<p align="center">
  <img src="docs/assets/logitech-sync-mcp-bouchecousue-hero.webp" alt="BoucheCousue character holding a secured cable that connects an AI assistant to Logitech Sync meeting-room equipment" width="1200">
</p>

A read-only [Model Context Protocol](https://modelcontextprotocol.io/) server for the Logitech Sync Cloud API. It turns the API's place inventory endpoint into nine focused tools that AI clients can use to inspect rooms, desks, devices, health, occupancy, coverage, environmental readings, and network information.

The server is written in Python, managed with [UV](https://docs.astral.sh/uv/), and connects to Logitech Sync with mutual TLS (mTLS). Certificate material stays on the local machine and is never accepted as a tool argument or returned in a tool response.

This is an independent integration and is not affiliated with or endorsed by Logitech. See
[Notices](NOTICE.md).

> [!IMPORTANT]
> This integration is strictly read-only. Logitech Sync Cloud API 0.1.4 exposes the inventory
> operation `GET /org/{orgId}/place`; this project does not provide write, update, or delete
> operations. Authorized administrators can obtain the vendor API documentation from Sync Portal.

## Tools

| Tool | Purpose |
|---|---|
| `logitech_sync_check_connection` | Validate the configuration, mTLS connection, license, and organisation access with a minimal request. |
| `logitech_sync_list_places` | Read a native page of rooms or desks with explicit projection and cursor controls. |
| `logitech_sync_search_inventory` | Search places and devices by name, ID, serial number, version, contract, IP address, MAC address, or hostname. |
| `logitech_sync_get_inventory_summary` | Summarise places, coverage, device types, models, versions, statuses, and health. |
| `logitech_sync_list_device_issues` | Find offline, warning, error, stale, or incomplete devices. |
| `logitech_sync_get_occupancy_report` | Report occupancy, known capacity, utilisation, and over-capacity places. |
| `logitech_sync_get_environment_report` | Read and filter available Spot and Rally Board sensor measurements without inventing health thresholds. |
| `logitech_sync_get_coverage_report` | Audit contracts, licences, and warranties as of a given date. |
| `logitech_sync_list_network_inventory` | Inventory IP addresses, MAC addresses, hostnames, and wired or Wi-Fi interfaces. |

All tools declare `readOnlyHint=true`, `destructiveHint=false`, `idempotentHint=true`, and `openWorldHint=true`.

## Requirements

- [UV](https://docs.astral.sh/uv/)
- A Logitech Sync organisation ID from **Sync Portal → Settings → Sync Cloud API**
- A PEM client certificate and its matching private key
- A compatible Logitech Select, Essential, or Sync Plus license

## Quick start

```bash
git clone https://github.com/bouchecousue/logitech-sync-mcp.git
cd logitech-sync-mcp
cp .env.example .env
```

Place your credentials at the default paths:

```text
client-certificate/certificate.pem
client-certificate/privateKey.pem
```

Set `LOGITECH_SYNC_ORG_ID` in `.env`, restrict the private key, then install and start the server:

```bash
chmod 600 client-certificate/privateKey.pem
uv sync --all-groups --no-editable
uv run --no-editable python run_server.py
```

The last command starts a stdio MCP server and waits for protocol messages on standard input. See the complete [Getting Started guide](docs/GETTING_STARTED.md) for certificate setup, client configuration, validation, and troubleshooting.

## MCP client configuration

Generic stdio configuration:

```json
{
  "mcpServers": {
    "logitech-sync": {
      "command": "uv",
      "args": [
        "--directory",
        "/path/to/logitech-sync-mcp",
        "run",
        "--no-editable",
        "python",
        "/path/to/logitech-sync-mcp/run_server.py"
      ]
    }
  }
}
```

The server loads `.env` from the project directory. Keep credentials out of the MCP client configuration when possible so they are not duplicated across configuration files.

## Configuration

| Variable | Default | Description |
|---|---|---|
| `LOGITECH_SYNC_ORG_ID` | none | Required organisation ID from Logitech Sync Portal. |
| `LOGITECH_SYNC_API_BASE_URL` | `https://api.sync.logitech.com/v1` | Documented API server; override only for administration or testing. |
| `LOGITECH_SYNC_CERT_FILE` | `client-certificate/certificate.pem` | Client certificate path; an absolute path is recommended. |
| `LOGITECH_SYNC_KEY_FILE` | `client-certificate/privateKey.pem` | Private key path; an absolute path is recommended. |
| `LOGITECH_SYNC_CA_FILE` | public CA bundle | Optional custom CA bundle. |
| `LOGITECH_SYNC_TIMEOUT_SECONDS` | `30` | Overall timeout for one attempt. |
| `LOGITECH_SYNC_CACHE_TTL_SECONDS` | `60` | Short in-memory cache to reduce quota usage. |
| `LOGITECH_SYNC_MAX_RETRIES` | `3` | Bounded retries for `429/502/503/504` and transport errors. |
| `LOGITECH_SYNC_MIN_REQUEST_INTERVAL_SECONDS` | `1` | Minimum interval between network attempts. |
| `LOGITECH_SYNC_TRUST_ENV` | `false` | Explicitly allow HTTPX environment proxies and CA settings. |
| `LOGITECH_SYNC_FIXTURE_FILE` | none | Offline fixture mode for tests and evaluations. |

The organisation ID is a separate value: the server never attempts to infer it from the X.509 certificate subject.

## Pagination, quotas, and output

According to the supplied Logitech documentation, the API allows 14,400 requests per day, supports a sustained rate of one request per second, and recommends exponential backoff. The client therefore:

- serialises network attempts at a minimum one-second interval;
- honours `Retry-After` without retrying early;
- applies bounded exponential backoff with jitter;
- caches pages briefly and caps the cache at 256 pages;
- detects cursor loops;
- bounds workflows with `page_size`, `max_pages`, and `max_results`;
- exposes `nextResultOffset` when an aggregated result has another local page;
- keeps text and `structuredContent` within a combined MCP response budget and reports truncation explicitly.

Tools support `markdown` and `json` text rendering and return schema-validated `structuredContent`. An omitted `projection` preserves Logitech's default projection, while `[]` requests place IDs only. Device child projections automatically include their required parent projection.

## Security model

- `.env`, `client-certificate/`, private-key formats, caches, and local tooling files are excluded from Git.
- On POSIX systems, startup fails if the private key is readable by the group or other users.
- Server certificate verification remains enabled; the implementation has no `verify=False` path.
- HTTP redirects are disabled so the client certificate is not presented to another host.
- PEM data is never exposed through MCP arguments or results.
- Application logs never use stdout, which is reserved for the stdio protocol.
- API-provided strings are treated as untrusted data and escaped in Markdown output.
- The API URL and secret paths are administrator configuration, not model-controlled tool inputs.

Before publishing a fork or opening a pull request, run:

```bash
git status --short
git check-ignore -v .env client-certificate/privateKey.pem
```

Never commit an organisation ID, certificate, private key, captured API response, or real inventory fixture.

## Development

```bash
uv sync --all-groups --no-editable
uv run --no-editable ruff check .
uv run --no-editable ruff format --check .
PYTHONPATH=src uv run --no-sync pytest --cov=logitech_sync_mcp
uv run --no-editable python -m compileall -q src
```

The live test consumes API quota and is disabled by default:

```bash
LOGITECH_SYNC_RUN_LIVE=1 uv run --no-editable pytest -m live tests/test_live.py
```

The deterministic [evaluation set](evals/evaluation.xml) uses the versioned synthetic fixture, never a live inventory.

## Documentation

- [Getting Started](docs/GETTING_STARTED.md)
- [Architecture](docs/ARCHITECTURE.md)
- [French README](README.fr.md)
- [Contributing](CONTRIBUTING.md)
- [Security policy](SECURITY.md)
- [Changelog](CHANGELOG.md)
- [Notices](NOTICE.md)

## License

Released under the [MIT License](LICENSE).