# AbleSign MCP

A Python Model Context Protocol server for the
[AbleSign digital signage API](https://apidocs.ablesign.tv/).

The purpose of this project is simple: let AI agents operate AbleSign digital
signage without making them speak REST by hand. It was fully vibe coded. There
is no claim that this is sacred architecture or precious artisanal software.
The agents do not care; they just have to do their jobs with it.

It exposes all 44 documented API operations as MCP tools:

- screens and screen playlists
- screen groups, membership, and group playlists
- media folders and media files
- AbleSign's initiate/finish upload and replacement flows
- web apps
- workspaces and workspace users

## Requirements

- Nix, or Python 3.11+ when installing with `uv`
- an AbleSign API key, created in **AbleSign CMS → Account → API Keys**

## Install and run

Install the `ablesign-mcp` binary from the flake:

```bash
nix profile install github:MartinLoeper/ablesign-mcp
ABLESIGN_API_KEY=ak_your_key ablesign-mcp
```

You can also run it directly without installing it:

```bash
ABLESIGN_API_KEY=ak_your_key \
  nix run github:MartinLoeper/ablesign-mcp
```

To install or run the current checkout instead, replace
`github:MartinLoeper/ablesign-mcp` with `.`.

Using `uv` for a source checkout:

```bash
cp .env.example .env
# Set ABLESIGN_API_KEY in .env, then export it or use your preferred env loader.
uv sync
ABLESIGN_API_KEY=ak_your_key uv run ablesign-mcp
```

The default transport is stdio. To run a Streamable HTTP server:

```bash
ABLESIGN_API_KEY=ak_your_key \
  ablesign-mcp --transport streamable-http
```

Clients then connect to `http://127.0.0.1:8000/mcp`.

## MCP client configuration

For a stdio MCP client, use:

```json
{
  "mcpServers": {
    "ablesign": {
      "command": "ablesign-mcp",
      "env": {
        "ABLESIGN_API_KEY": "ak_your_key",
        "ABLESIGN_WORKSPACE_ID": "123"
      }
    }
  }
}
```

`ABLESIGN_WORKSPACE_ID` is optional. Without it, AbleSign uses the account's
default workspace.

## Environment

| Variable | Required | Default | Purpose |
| --- | --- | --- | --- |
| `ABLESIGN_API_KEY` | yes | — | Bearer token used for every API request |
| `ABLESIGN_WORKSPACE_ID` | no | account default | Sent as `Workspace-Id` |
| `ABLESIGN_BASE_URL` | no | `https://api.ablesign.tv/api/v1` | API base URL |
| `ABLESIGN_TIMEOUT` | no | `30` | request timeout in seconds |
| `ABLESIGN_MCP_TRANSPORT` | no | `stdio` | `stdio`, `streamable-http`, or `sse` |
| `ABLESIGN_MCP_HOST` | no | `127.0.0.1` | HTTP bind host |
| `ABLESIGN_MCP_PORT` | no | `8000` | HTTP bind port |

## Media uploads

AbleSign uses a three-step upload flow:

1. Call `initiate_media_upload` (or `initiate_media_replacement`).
2. Upload the raw file bytes with HTTP `PUT` to the returned signed URL.
3. Call `complete_media_upload` (or `complete_media_replacement`) with the
   returned upload ID.

The MCP server exposes the authenticated AbleSign steps. Uploading bytes to the
temporary signed storage URL is intentionally left to the caller so the server
does not receive arbitrary local filesystem access.

## Development

```bash
nix build
nix run . -- --help

uv sync --extra dev
uv run pytest
uv run ruff check .
uv run ruff format --check .
```

The API is currently marked beta by AbleSign. The server returns AbleSign errors
with their HTTP status, error code, and message so callers can react to
validation and rate-limit failures.

## Philosophy and license

This project is released under the [MIT License](LICENSE). Do whatever you would
like with it. Use it, fork it, break it, fix it, sell it, or rewrite it 1,000
times. I really do not care. My agents do not care either. They just have to do
their job with it and make gastronomy great again. lol