{
  "markdown": "# Slack Lists MCP Server\n\n<!-- mcp-name: io.github.justadityaraj/slack-lists-mcp -->\n\n[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)\n[![Python Version](https://img.shields.io/badge/python-3.10%2B-blue.svg)](https://www.python.org/)\n[![MCP Version](https://img.shields.io/badge/MCP-1.2.0%2B-brightgreen.svg)](https://modelcontextprotocol.io/)\n\n**A Model Context Protocol (MCP) server that gives AI assistants full read and write access to Slack Lists.**\n\nThis server acts as a bridge between AI models and Slack, enabling seamless creation, retrieval, updating, deletion, filtering, and management of Slack List items through a standardized protocol. It empowers AI assistants like Claude Desktop to become powerful productivity tools for managing tasks, projects, and data within Slack.\n\nThis project provides a complete package with:\n- **Comprehensive Toolset**: Create, query, update, delete, filter, and export list items.\n- **Robust Implementation**: Built with Python, FastMCP, and best practices.\n- **Easy Deployment**: Simple setup with environment variables.\n- **Detailed Documentation**: Full README, tool reference, and examples.\n- **Extensible Design**: Easily add new tools and functionality.\n\nThe write paths have been verified against a live Slack workspace (see [Verification status](#verification-status)).\n\n\n\n\n## Features\n\nThis MCP server provides a rich set of tools for interacting with Slack Lists:\n\n- **Create Single Item**: Add one item to a list with detailed fields.\n- **Bulk Create Items**: Add multiple items at once with built-in rate limiting to respect Slack's API.\n- **Retrieve Items**: Fetch a list of items with optional metadata.\n- **Update Items**: Update any cell on an existing item — check a task off, reassign it, reschedule it, or edit any field (full task management).\n- **Delete Items**: Permanently remove an item from a list.\n- **Discover Columns**: Infer a list's column IDs, types, and select option IDs from its existing items (Slack exposes no schema API, so this saves you from hunting for IDs in browser dev tools).\n- **Filter Items**: Powerful server-side filtering based on any field value (status, assignee, priority, etc.).\n- **Export Data**: Export list items to JSON or CSV format for analysis or backup.\n- **Subtask Creation**: Create sub-items under a parent item.\n- **Full Field Support**: Works with all Slack List field types (text, date, user, select, checkbox, number, email, phone).\n- **Error Handling**: Robust error handling and clear feedback for failed operations.\n\n\n\n\n## Getting Started\n\nFollow these steps to get your Slack Lists MCP server up and running.\n\n### Prerequisites\n\n- **Python 3.10+**\n- **Slack Workspace**: A Slack workspace where you have permission to install apps.\n- **Slack Bot Token**: A bot token with `lists:read` and `lists:write` scopes.\n\n### 1. Create a Slack App\n\n1. Go to the [Slack API website](https://api.slack.com/apps) and click **Create New App**.\n2. Choose \"From scratch\", give your app a name (e.g., \"Lists MCP Server\"), and select your workspace.\n3. In the app settings, go to **OAuth & Permissions**.\n4. Under **Bot Token Scopes**, add the following scopes:\n   - `lists:read`\n   - `lists:write`\n5. Click **Install to Workspace** at the top of the page and authorize the app.\n6. Copy the **Bot User OAuth Token** (it starts with `xoxb-`). This is your `SLACK_BOT_TOKEN`.\n\n### 2. Installation\n\nClone the repository and install the dependencies:\n\n```bash\n# Clone the repository\ngit clone https://github.com/justadityaraj/slack-lists-mcp.git\ncd slack-lists-mcp\n\n# Create and activate a virtual environment\npython3 -m venv .venv\nsource .venv/bin/activate\n\n# Install dependencies\npip install -r requirements.txt\n```\n\n### 3. Configuration\n\nCreate a `.env` file by copying the example:\n\n```bash\ncp .env.example .env\n```\n\nOpen the `.env` file and set your `SLACK_BOT_TOKEN`:\n\n```dotenv\nSLACK_BOT_TOKEN=xoxb-your-bot-token-here\n```\n\nThe server loads this `.env` (from the project root) automatically on startup, so you do not need to put the token anywhere else. A real `SLACK_BOT_TOKEN` environment variable always takes precedence over the file.\n\n### 4. Running the Server\n\nYou can run the server directly from the command line:\n\n```bash\npython src/slack_lists_server.py\n```\n\nThe server will start and listen for MCP requests over STDIO.\n\n### 5. Connecting to an MCP Host (e.g., Claude Desktop)\n\nTo use the server with an AI assistant, you need to configure your MCP host.\n\n1. Open your MCP host's configuration file (e.g., `mcp_servers.json` for Claude Desktop).\n2. Add a new server entry pointing to your `slack_lists_server.py` script.\n\n**Example `mcp_servers.json` configuration:**\n\n```json\n{\n  \"mcpServers\": {\n    \"slack-lists\": {\n      \"command\": \"/path/to/your/.venv/bin/python\",\n      \"args\": [\"/path/to/slack-lists-mcp-server/src/slack_lists_server.py\"],\n      \"env\": {\n        \"SLACK_BOT_TOKEN\": \"xoxb-your-bot-token-here\"\n      }\n    }\n  }\n}\n```\n\n**Important**: Make sure to use the absolute path to your Python executable and the server script. Because the server reads the token from the project `.env`, the `env` block above is optional.\n\nOnce configured, restart your MCP host. The Slack Lists tools should now be available to your AI assistant.\n\n#### Claude Code (CLI)\n\n```bash\nclaude mcp add slack-lists -s user -- /abs/path/.venv/bin/python /abs/path/slack-lists-mcp/src/slack_lists_server.py\n```\n\nNo `-e SLACK_BOT_TOKEN=...` is needed; the server picks the token up from `.env`.\n\n\n\n\n## Tool Reference\n\nThis server exposes the following tools to your AI assistant. Each tool is designed to be intuitive and powerful, with clear descriptions and parameters.\n\n--- \n\n### `create_list_item`\n\nCreates a single new item in a Slack List.\n\n**Description:**\nThis tool creates one item in the specified Slack List. The item must have at least a title field, and can include additional fields as needed. All field values are validated against the list's schema.\n\n**Parameters:**\n- `list_id` (string, required): The ID of the Slack List (e.g., `F1234ABCD`).\n- `title` (string, required): The main title/text for the item.\n- `title_column_id` (string, optional): Column ID for the title field (defaults to `Col10000000`).\n- `additional_fields` (string, optional): JSON string of additional fields. See [Field Formats](#field-formats) for details.\n- `parent_item_id` (string, optional): Optional parent item ID to create a subtask.\n\n**Example Prompt:**\n> \"Create a new task in my project list `F1234ABCD` with the title 'Finish Q4 report' and a due date of 2024-12-20.\"\n\n--- \n\n### `create_multiple_list_items`\n\nCreates multiple items in a Slack List with rate limiting.\n\n**Description:**\nThis tool allows bulk creation of list items. Each item is created individually with proper rate limiting to respect Slack's API limits (~50 requests per minute).\n\n**Parameters:**\n- `list_id` (string, required): The ID of the Slack List.\n- `items_data` (string, required): JSON array of items to create. See [Bulk Creation Format](#bulk-creation-format) for details.\n- `title_column_id` (string, optional): Column ID for the title field.\n- `rate_limit_delay` (float, optional): Delay between requests in seconds (default: 1.2s).\n\n**Example Prompt:**\n> \"Add these three tasks to my list `F1234ABCD`: 1. Design mockups (due 12/10), 2. Write tests (due 12/15), 3. Update documentation (due 12/20).\"\n\n--- \n\n### `get_list_items`\n\nRetrieves items from a Slack List.\n\n**Description:**\nThis tool fetches items from the specified Slack List with optional metadata. Use this to view current list contents, check item details, or prepare data for filtering.\n\n**Parameters:**\n- `list_id` (string, required): The ID of the Slack List.\n- `limit` (integer, optional): Maximum number of items to retrieve (default: 50, max: 100).\n- `include_metadata` (boolean, optional): Whether to include creation/update metadata (default: True).\n\n**Example Prompt:**\n> \"Show me the 10 most recent items in my 'Tasks' list `F5678EFGH`.\"\n\n--- \n\n### `filter_list_items`\n\nFilters and retrieves items from a Slack List based on field values.\n\n**Description:**\nThis tool allows you to search and filter list items by specific field values. Useful for finding items with a specific status, assignee, priority, or any other field.\n\n**Parameters:**\n- `list_id` (string, required): The ID of the Slack List.\n- `filter_column_id` (string, required): Column ID to filter by.\n- `filter_value` (string, required): Value to search for.\n- `filter_operator` (string, optional): How to match the value. See [Filter Operators](#filter-operators) for options.\n- `max_items` (integer, optional): Maximum number of items to process (default: 100).\n\n**Example Prompt:**\n> \"Find all tasks in list `F1234ABCD` assigned to me that are marked as 'High' priority.\"\n\n--- \n\n### `export_list_items`\n\nExports items from a Slack List to a structured data format.\n\n**Description:**\nThis tool exports list items to JSON or CSV format, with optional filtering. Useful for backup, analysis, or integration with other systems.\n\n**Parameters:**\n- `list_id` (string, required): The ID of the Slack List.\n- `export_format` (string, optional): Output format - `json` or `csv` (default: `json`).\n- `filter_column_id` (string, optional): Optional column ID to filter by.\n- `filter_value` (string, optional): Value to filter for (required if `filter_column_id` is provided).\n- `filter_operator` (string, optional): Filter operator.\n\n**Example Prompt:**\n> \"Export all completed tasks from my project list `F1234ABCD` to a CSV file.\"\n\n---\n\n### `update_list_item`\n\nUpdates one or more cells on an existing Slack List item (row). This is the tool for full task management: check a task off, reassign it, reschedule it, or edit any field — in a single call.\n\n**Description:**\nUpdates the given columns on the item identified by `row_id`. Find the `row_id` with `get_list_items` or `filter_list_items` (it is each item's `id`, e.g. `Rec1234567`). Find `column_id`s and select option IDs with `discover_list_columns`.\n\n**Parameters:**\n- `list_id` (string, required): The ID of the Slack List (e.g., `F1234ABCD`).\n- `row_id` (string, required): The ID of the item/row to update (e.g., `Rec1234567`).\n- `fields` (string, required): JSON array of cells to update. Each cell is `{\"column_id\": \"...\", \"type\": \"...\", \"value\": ...}`. See [Field Formats](#field-formats). Supported types: `text`, `date`, `user`, `select`, `checkbox`, `number`, `email`, `phone`.\n\n**Example Prompt:**\n> \"Mark task `Rec1234567` in list `F1234ABCD` as done, reassign it to `U1234567`, and move the due date to 2025-09-20.\"\n\n---\n\n### `delete_list_item`\n\nPermanently deletes an item (row) from a Slack List. This cannot be undone.\n\n**Parameters:**\n- `list_id` (string, required): The ID of the Slack List (e.g., `F1234ABCD`).\n- `row_id` (string, required): The ID of the item/row to delete (e.g., `Rec1234567`).\n\n**Example Prompt:**\n> \"Delete item `Rec1234567` from list `F1234ABCD`.\"\n\n---\n\n### `discover_list_columns`\n\nDiscovers a list's columns by inspecting its existing items. Slack exposes no API to read a list's schema directly, so this infers each column's ID, type, a sample value, and (for select columns) the option IDs from the data already in the list. Use it to find the `column_id` and select option IDs needed by `create_list_item` and `update_list_item`.\n\n**Note:** A column is only discoverable if at least one item has a value in it. Empty columns will not appear.\n\n**Parameters:**\n- `list_id` (string, required): The ID of the Slack List (e.g., `F1234ABCD`).\n- `sample_size` (integer, optional): How many items to scan, 1-1000 (default: 100).\n\n**Example Prompt:**\n> \"What columns does list `F1234ABCD` have, and what are the status option IDs?\"\n\n\n## Data Formats\n\n### Field Formats\n\nWhen using `create_list_item` or `create_multiple_list_items`, you need to provide field data in a specific JSON format. The `additional_fields` and `items_data` parameters expect a JSON string.\n\nEach field is an object with `column_id`, `type`, and `value`:\n\n```json\n[\n  {\n    \"column_id\": \"Col10000001\",\n    \"type\": \"date\",\n    \"value\": \"2024-12-31\"\n  },\n  {\n    \"column_id\": \"Col10000002\",\n    \"type\": \"select\",\n    \"value\": [\"OptionID123\"]\n  },\n  {\n    \"column_id\": \"Col10000003\",\n    \"type\": \"user\",\n    \"value\": [\"U1234567\", \"U2345678\"]\n  },\n  {\n    \"column_id\": \"Col10000004\",\n    \"type\": \"checkbox\",\n    \"value\": true\n  }\n]\n```\n\n**Supported Field Types:**\n- `text`: String value.\n- `date`: String in `YYYY-MM-DD` format.\n- `user`: Array of Slack user IDs (e.g., `[\"U1234567\"]`).\n- `select`: Array of select option IDs.\n- `checkbox`: Boolean `true` or `false`.\n- `number`: Numeric value.\n- `email`: String email address.\n- `phone`: String phone number.\n\n### Bulk Creation Format\n\nThe `items_data` parameter for `create_multiple_list_items` expects a JSON array where each object represents an item to be created.\n\n```json\n[\n  {\n    \"title\": \"First Task\",\n    \"fields\": [\n      {\"column_id\": \"Col123\", \"type\": \"date\", \"value\": \"2024-12-15\"}\n    ]\n  },\n  {\n    \"title\": \"Second Task\",\n    \"fields\": [\n      {\"column_id\": \"Col123\", \"type\": \"date\", \"value\": \"2024-12-20\"},\n      {\"column_id\": \"Col456\", \"type\": \"user\", \"value\": [\"U1234567\"]}\n    ]\n  }\n]\n```\n\n### Filter Operators\n\nThe `filter_list_items` tool supports the following operators:\n\n- `contains`: Field contains the value (case-insensitive).\n- `equals`: Field exactly matches the value (case-insensitive).\n- `not_equals`: Field does not match the value.\n- `not_contains`: Field does not contain the value.\n- `exists`: Field has any non-empty value.\n- `not_exists`: Field is empty or missing.\n\n\n\n\n## Troubleshooting\n\n- **`invalid_auth` Error**: Your `SLACK_BOT_TOKEN` is likely incorrect or has been revoked. Generate a new one and update your `.env` file.\n- **`missing_scope` Error**: Ensure your Slack app has both `lists:read` and `lists:write` scopes.\n- **`list_not_found` Error**: The `list_id` you provided is incorrect. Double-check the ID in Slack.\n- **Server Not Responding**: Make sure the server is running and that the path in your MCP host configuration is correct. Check for any errors in the server logs.\n- **JSON Errors**: Validate your JSON strings for `additional_fields` and `items_data` using an online validator.\n\n## How to Find List and Column IDs\n\n1. **List ID**: Open the list in Slack. The ID is the last part of the URL (e.g., `https://app.slack.com/client/.../F1234ABCD`).\n2. **Column ID**: The easiest way is the `discover_list_columns` tool, which lists every column's ID, type, and select option IDs by inspecting the list's existing items. (You can also inspect browser network requests, or read the raw output of `get_list_items`.)\n\n## Contributing\n\nContributions are welcome! If you have ideas for new features, bug fixes, or improvements, please open an issue or submit a pull request. See `CONTRIBUTING.md` for more details.\n\n## Verification status\n\nAll tools are covered by unit tests and have been exercised against a live Slack workspace: `discover_list_columns`, `create_list_item`, `update_list_item` (text, user, date, and checkbox cells, including a single multi-cell \"check off + reassign + reschedule\" update), and `delete_list_item` all round-trip correctly.\n\nOne field shape differs from the published docs: **checkbox cells take a bare boolean** (`\"checkbox\": true`), not an array. The docs show `\"checkbox\": [boolean]`, but the live API rejects the array form with `invalid_arguments` and returns the value as a bare bool, so this server sends a bare bool.\n\n## Credits\n\nThis project is derived from [maplehilllabs/mcp-slack-lists](https://github.com/maplehilllabs/mcp-slack-lists) (MIT), extended with `update_list_item`, `delete_list_item`, and `discover_list_columns` plus full field-type support.\n\n## License\n\nThis project is licensed under the MIT License. See the [LICENSE](LICENSE) file for details.\n\n<!-- by [Aditya Raj Singh](https://adityarajsingh.com/) -->\n\n\n",
  "bytes": 16022,
  "sha": "501f608831b2604461254c7ba4d6e4c7614a370a10edab591ab8031b8e60d0dd",
  "repo_slug": "justadityaraj/slack-lists-mcp",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_justadityaraj_slack_lists_mcp_1f5c8d65/readme"
}