capture-and-slack-mcp

An MCP server that relays a result screenshot to Slack so you can review a coding agent's output without opening the app.

You hand an agent a task on your desktop app (e.g. Clonify, a Qt/VTK CAD tool), and end it with "…and send me the result via the capture-and-slack MCP." The agent renders the result to an image and this server posts it to your Slack DM or a channel. You glance at Slack instead of launching the app.

This server does not drive any GUI — it only relays images.

How it fits the loop

agent finishes a task
  ├─ (A, preferred)  runs a repro/test that offscreen-renders the result → /tmp/result.png
  │                     → send_to_slack(["/tmp/result.png"], "3mm gaussian emboss done")
  └─ (B, fallback)   the app window is on screen (X11)
                        → capture_window_and_post("result", window="Clonify")
        → Slack files_upload_v2 → you see the image in your Slack DM/channel

Path A is the robust one: the app's own headless render (VTK SetOffScreenRendering(1) + vtkWindowToImageFilter, optionally under QT_QPA_PLATFORM=offscreen) writes a PNG, and this server just posts it. Path B screenshots the live window and is for when no offscreen render exists.

Related MCP server: Slack Note Capture MCP Server

Tools

Image paths must be absolute (the server's working directory differs from the agent's). Errors come back as a JSON envelope {"code","message","hint"} in an isError result.

Requirements

• uv and Python ≥ 3.12.

• A Slack bot token (see Slack setup — image uploads need files_upload_v2; webhooks can't attach files).

• For live capture only: an X11 session with ImageMagick import or KDE spectacle installed. Precise per-window targeting uses xdotool if present, else xwininfo (already on most X11 desktops) — no install needed. Match by window title or WM_CLASS substring; a class like QClonifyApp disambiguates from an editor tab that merely has "Clonify" in its title.

Slack setup (one time)

1. Go to https://api.slack.com/apps → Create New App → From an app manifest, pick your workspace, and paste:

   {
     "display_information": { "name": "Capture and Slack Bot" },
     "features": { "bot_user": { "display_name": "capture-and-slack", "always_online": true } },
     "oauth_config": { "scopes": { "bot": ["files:write", "chat:write", "im:write"] } },
     "settings": { "org_deploy_enabled": false, "socket_mode_enabled": false }
   }

   Scopes: files:write (upload), chat:write (the caption), im:write (open a DM when the destination is a user ID; drop it if you'll only post to channels).

2. Install to Workspace → authorize → copy the Bot User OAuth Token (xoxb-…) from OAuth & Permissions.

3. Pick a destination ID:

   • DM to yourself: your member ID U… (Slack profile → ⋮ → Copy member ID). The bot can DM you without an invite.

   • A channel: the channel ID C… (channel → View details), and run /invite @capture-and-slack in it.

4. Provide the token to the server (do not commit it): cp .env.example .env and fill in SLACK_BOT_TOKEN and SLACK_DEFAULT_CHANNEL, or export them in your shell.

5. (Optional, for precise window targeting) sudo pacman -S xdotool.

Install & test

uv sync
uv run pytest

Register with Claude Code

Project-scoped (.mcp.json is already in this repo):

{
  "mcpServers": {
    "capture-and-slack": {
      "command": "uv",
      "args": ["run", "--directory", "/home/baho/Desktop/capture-and-slack-mcp", "capture-and-slack-mcp"]
    }
  }
}

The server reads SLACK_BOT_TOKEN / SLACK_DEFAULT_CHANNEL from the environment or a git-ignored .env. (Keep the token out of .mcp.json, which is committed.)

Configuration

Development

Module map — only server.py imports the MCP SDK:

• server.py — the 3 tools + main().

• slack_client.py — slack_sdk wrapper: files_upload_v2, DM resolution, error translation.

• capture.py — X11/KDE window capture. Layered fallback: resolve window id (xdotool → xwininfo) and grab it directly → active window (spectacle) → fullscreen.

• images.py — Pillow: path/content validation, auto-trim, PNG byte reads.

• config.py — env-driven settings (with a tiny .env loader).

• errors.py — ErrorCode + CaptureSlackError (JSON envelope).

License

MIT