slack-personal-mcp

An MCP server that works in Slack with your own user token (xoxp-). Messages, files, reactions and status changes come from you, without the "via app" badge a bot token adds.

• Every tool that touches Slack takes an explicit workspace alias, so a read or a send never lands in the wrong workspace by default.

• A style gate checks outgoing text for AI typography (em dash, curly quotes, ellipsis character), stock AI phrases and unapproved promises before anything is sent.

• SLACK_READ_ONLY=1 hides every tool that changes Slack or local files; SLACK_WRITE_CHANNELS limits writes to listed conversations.

It runs over stdio on your machine. The official Slack MCP server is a hosted service with OAuth and admin approval; this one is for a person who wants their own token on their own computer.

Tools

30 tools. In the table, R is read-only, W writes to Slack, D deletes or overwrites something. SLACK_READ_ONLY=1 leaves the 19 R tools.

*:read and *:history stand for the channels:, groups:, im: or mpim: scope that matches the conversation type. Message authors get names from a directory cache, which needs users:read. In every writing tool channel_id may be a user id U...: the message, file or reaction goes to your DM with that person, which needs im:write.

If a scope is missing, the error names it. Add it under User Token Scopes, reinstall the app and put the new token in .env.

Related MCP server: Slack MCP Server

How the tools behave

Sending. format="markdown" (the default) sends standard Markdown as markdown_text, up to 12,000 characters; format="mrkdwn" sends Slack's own markup as text, up to 40,000. Link previews are off unless unfurl_links=true. To reply in a thread, pass the ts of the thread's first message as thread_ts, not the ts of a reply. reply_broadcast=true also shows the reply in the channel.

Your messages only. slack_edit_message and slack_delete_message check the author first and refuse messages by anyone else, even when an admin token could change them.

Approval. The MCP client, not this server, asks you before it calls a tool. Tools carry MCP annotations (read-only, destructive, idempotent), so a client can ask only for writes. Keep approval on for writes and uploads and read the text or path before you allow it.

Files. slack_upload_file reads and slack_download_file writes only inside SLACK_FILE_ROOTS (default: home and the temp folders). Hidden files and folders such as ~/.ssh or .env, and ~/Library and ~/AppData under the default roots, are refused, symlinks included. Downloads go to a temporary file and replace an existing copy only once the size matches. Files stored outside Slack return their external_url instead. The file tools work on macOS, Linux and Windows.

Pages. Reads return one page at a time and say whether more exist. slack_read_channel returns {messages, next_cursor, has_more}: pass next_cursor back as cursor with the same other arguments. slack_read_thread adds complete, and with all_pages=true follows the cursor up to max_pages (default 10). slack_search_messages returns {messages, total, page, pages}; slack_search and slack_list_scheduled return next_cursor. oldest and latest take Slack timestamps such as 1729612345.123456.

Messages. Each message keeps Slack's ts and text and adds time (ISO 8601, UTC), user_id and user_name, thread fields, reactions and files. Text from legacy attachments is in attachments_text, text from blocks in blocks_text; a rich_text block that only repeats text is left out. Empty fields are dropped.

Names. slack_find_user and slack_find_channel search full users.list and conversations.list directories, cached in memory for an hour per workspace; refresh=true reloads. An exact email goes through users.lookupByEmail and a U... id through users.info, without the directory.

Unread. Slack's API has no unread inbox like the app has. slack_unread takes the conversations you name and counts messages from others after your read marker.

Search. slack_search_messages uses the classic search.messages. slack_search uses the Real-time Search API, which works for internal apps; if your workspace does not offer it, the error says so.

Results. Tools return structured content with an output schema. Errors come back as MCP tool errors.

Style gate

src/slack_personal_mcp/style.py checks every message, edit, scheduled message, status, upload comment and file title before it leaves:

• Errors block the send: AI typography (em and en dash, ellipsis character, curly quotes, non-breaking space, bullet character) and stock AI phrases.

• Warnings block the send unless allow_promise=true: concrete promises and deadlines.

Code, URLs, Slack mentions (<@U...>, <#C...>, <!here>) and quoted lines are not checked; link labels are. Each finding gives a zero-based character range. Phrase lists cover English and Russian. SLACK_STYLE_GATE=off turns the gate off for sends; slack_lint works either way.

Setup

Requires Python 3.10+ and uv.

git clone https://github.com/oviron/slack-personal-mcp
cd slack-personal-mcp
uv sync

uv run pytest runs the offline tests.

Slack app and token

Each workspace needs its own Slack app.

1. At https://api.slack.com/apps choose Create New App, then From an app manifest, pick the workspace and paste slack-app-manifest.yaml.

2. Install to Workspace. Workspaces that need admin approval for apps ask an admin first.

3. Copy the User OAuth Token (xoxp-...) from OAuth & Permissions.

The manifest asks for every scope in the table above. Remove the ones you don't need before installing; the matching tools then fail with missing_scope. channels:write and groups:write are only for slack_mark_read, but they also allow managing channels, so leave them out if you don't need it.

Keep token rotation off: the manifest sets token_rotation_enabled: false. With rotation on, Slack issues xoxe.xoxp- tokens that expire after 12 hours, this server does not refresh them, and Slack does not let you turn rotation off again. An app with rotation on has to be replaced by a new one.

The app is internal to your workspace, so Slack's May 2025 rate limits for commercially distributed apps (one conversations.history call a minute) do not apply. Don't distribute one app to other workspaces: create one per workspace.

Configuration

Tokens come from the environment, or from .env next to server.py (ignored by git; keep it chmod 600). Copy .env.example to start:

SLACK_USER_TOKEN_ACME=xoxp-...
SLACK_USER_TOKEN_SIDE_PROJECT=xoxp-...

Each SLACK_USER_TOKEN_<ALIAS> adds a workspace; SIDE_PROJECT becomes the alias side-project. slack_list_workspaces shows whose token each alias holds:

{"workspaces": [{"workspace": "acme", "configured": true, "team": "Acme", "team_id": "T0123",
  "url": "https://acme.slack.com/", "user": "jane", "user_id": "U0456"}]}

Registering with a client

The server speaks MCP over stdio. Point the client at the clone's Python and server.py; the examples use /path/to/slack-personal-mcp.

Claude Code:

claude mcp add slack-personal -- /path/to/slack-personal-mcp/.venv/bin/python /path/to/slack-personal-mcp/server.py

Codex, in ~/.codex/config.toml:

[mcp_servers.slack-personal]
command = "/path/to/slack-personal-mcp/.venv/bin/python"
args = ["/path/to/slack-personal-mcp/server.py"]

Claude Desktop (claude_desktop_config.json) and Cursor (.cursor/mcp.json):

{
  "mcpServers": {
    "slack-personal": {
      "command": "/path/to/slack-personal-mcp/.venv/bin/python",
      "args": ["/path/to/slack-personal-mcp/server.py"]
    }
  }
}

Without a clone, uv runs a tagged release straight from GitHub. There is no server.py next to it, so name the env file:

SLACK_ENV_FILE=~/.config/slack-personal-mcp/.env uvx --from git+https://github.com/oviron/slack-personal-mcp@v0.2.3 slack-personal-mcp

Troubleshooting

Changes to the code or .env take effect when the client restarts the server.

Releasing

The package is not published to PyPI or the MCP Registry; releases are git tags.

1. Bump the version in pyproject.toml and src/slack_personal_mcp/__init__.py, run uv lock, then merge.

2. Tag vX.Y.Z on main and create a GitHub release.

License

MIT