slack-file-upload-mcp

A one-tool MCP server that does the thing the normal Slack MCP can't: post a local file to Slack, with a message.

The Slack MCP sends text (slack_send_message) and reads files, but has no way to put a file from your disk into a channel. Run this alongside it and an agent can share a screenshot, CSV, log, or PDF directly.

The tool

slack_upload_file

Returns one line: Uploaded report.csv (4821 bytes) to C09ABCD1234 · file_id=F0… · ts=1756… · https://…. The ts is the share timestamp, so the Slack MCP can thread replies under the uploaded file.

Uploads go through Slack's current files.getUploadURLExternal → upload → files.completeUploadExternal flow (via slack_sdk's files_upload_v2); the retired files.upload endpoint is not used.

Related MCP server: Notion Uploader MCP

Setup

1. Token. A user token (xoxp-…) or bot token (xoxb-…) with:

   • files:write — required.

   • channels:read + groups:read — only needed to resolve #name → id. Passing a C… id works without them.

   • im:write — only needed to DM a U… user id.

   A bot token must be invited to the channel (/invite @yourapp); a user token posts as you.

   manifest.yaml in this repo creates an app with exactly those scopes: api.slack.com/apps → Create New App → From a manifest → pick the workspace → paste the file → Create → Install to Workspace (admin approval may be required) → OAuth & Permissions → copy the User OAuth Token (xoxp-…).

   It's deliberately a separate app from any existing one: adding a scope to an installed app forces a reinstall, which rotates that app's token and breaks whatever else was using it.

2. Register the server (token lives in the MCP env, not in the repo):

   claude mcp add slack-file-upload --scope user \
     --env SLACK_MCP_TOKEN=xoxp-your-token \
     -- uv run --directory /path/to/slack-file-upload-mcp slack-file-upload-mcp serve

3. Verify: SLACK_MCP_TOKEN=… uv run slack-file-upload-mcp whoami

Configuration

Guardrails

• Path must be absolute and resolve to an existing regular file; directories and symlink targets outside SLACK_FILE_UPLOAD_ALLOWED_DIRS are rejected (the path is resolve()d before the allowlist check).

• Empty files are rejected up front — Slack's upload-URL endpoint requires a non-zero length and fails opaquely on 0 bytes.

• Slack API errors are translated into actionable text (not_in_channel → "invite the app to the channel", missing_scope → which scopes).

CLI

uv run slack-file-upload-mcp serve                       # stdio MCP (also the bare default)
uv run slack-file-upload-mcp whoami                      # verify the token
uv run slack-file-upload-mcp upload ~/x.png '#general' -m 'here you go'

upload runs the exact code path the MCP tool runs — useful for smoke tests without a client.

Tests

uv run pytest              # offline; the Slack client is stubbed