Metadata-Version: 2.4
Name: mcp-discord-bot
Version: 2026.10.8.0
Summary: MCP Server for Discord automation via Discord Agent Proxy
Project-URL: Homepage, https://github.com/AceDataCloud/DiscordBotMCP
Project-URL: Documentation, https://platform.acedata.cloud/documents/development_discord_bot?utm_source=pypi&utm_medium=referral&utm_campaign=evergreen&utm_content=discord_bot_mcp_package_quick_start
Project-URL: Repository, https://github.com/AceDataCloud/DiscordBotMCP
Project-URL: Issues, https://github.com/AceDataCloud/DiscordBotMCP/issues
Project-URL: Changelog, https://github.com/AceDataCloud/DiscordBotMCP/blob/main/CHANGELOG.md
Author-email: AceDataCloud <support@acedata.cloud>
Maintainer-email: AceDataCloud <support@acedata.cloud>
License-Expression: MIT
License-File: LICENSE
Keywords: acedata,api,automation,bot,claude,discord,llm,mcp,model-context-protocol
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Communications :: Chat
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Requires-Python: >=3.10
Requires-Dist: httpx>=0.27.0
Requires-Dist: loguru>=0.7.0
Requires-Dist: mcp<2,>=1.2.0
Requires-Dist: pydantic>=2.0.0
Requires-Dist: python-dotenv>=1.0.0
Provides-Extra: all
Requires-Dist: build>=1.2.0; extra == 'all'
Requires-Dist: mypy>=1.10.0; extra == 'all'
Requires-Dist: pre-commit>=3.7.0; extra == 'all'
Requires-Dist: pytest-asyncio>=0.23.0; extra == 'all'
Requires-Dist: pytest-cov>=5.0.0; extra == 'all'
Requires-Dist: pytest>=8.0.0; extra == 'all'
Requires-Dist: respx>=0.21.0; extra == 'all'
Requires-Dist: ruff>=0.4.0; extra == 'all'
Requires-Dist: twine>=5.0.0; extra == 'all'
Provides-Extra: dev
Requires-Dist: mypy>=1.10.0; extra == 'dev'
Requires-Dist: pre-commit>=3.7.0; extra == 'dev'
Requires-Dist: ruff>=0.4.0; extra == 'dev'
Provides-Extra: release
Requires-Dist: build>=1.2.0; extra == 'release'
Requires-Dist: twine>=5.0.0; extra == 'release'
Provides-Extra: test
Requires-Dist: pytest-asyncio>=0.23.0; extra == 'test'
Requires-Dist: pytest-cov>=5.0.0; extra == 'test'
Requires-Dist: pytest>=8.0.0; extra == 'test'
Requires-Dist: respx>=0.21.0; extra == 'test'
Description-Content-Type: text/markdown

<!-- Generated by scripts/marketing_readmes.py from README.md; do not edit. -->
# MCP Discord Bot Server

A Model Context Protocol (MCP) server that provides tools for automating Discord
through a self-hosted [Discord Agent Proxy](https://platform.acedata.cloud?utm_source=pypi&utm_medium=referral&utm_campaign=evergreen&utm_content=discord_bot_mcp_package_platform) instance.

## Overview

The Discord Agent Proxy is a standalone service you deploy on AceDataCloud. It maintains
a persistent connection to Discord using your account credentials and exposes both an MCP
and REST API interface.

This MCP server wraps the Discord Agent Proxy's REST API, exposing Discord operations
as MCP tools for use with Claude, Cursor, and other MCP-compatible AI clients.

> ⚠️ **Warning**: Automating a personal Discord account (self-bot) violates Discord's Terms
> of Service. Use a dedicated account and keep automation frequency reasonable.

## Prerequisites

1. Create a Discord Agent Proxy application at [platform.acedata.cloud](https://platform.acedata.cloud/console/applications?utm_source=pypi&utm_medium=referral&utm_campaign=evergreen&utm_content=discord_bot_mcp_package_api_key) and activate a subscription. Instance resources are configured automatically; no instance size selection is needed.
2. Enter your Discord account credentials in the configuration page and deploy.
3. In the application's **Overview** tab, confirm the account is connected and copy the MCP endpoint and access token from the Discord account card. A running container does not guarantee a connected Discord account.

The **Documentation** tab lists all 14 REST operations with request parameters, response schemas, and code examples. Test `GET /api/whoami` there, or call `discord_whoami` after configuring this MCP server, to verify the connected account. Instance addresses and access tokens are filled in automatically in the console; tokens are hidden by default. Sending, editing, or deleting messages affects the real account, so confirm the target and content before testing.

**Download OpenAPI (JSON)** exports the instance address without its access token. To change Discord account credentials, use **Redeploy** in **Overview**.

## Connect to your Discord Agent Proxy

This package connects to **your own deployed Discord Agent Proxy**, not to the shared `https://<service>.mcp.acedata.cloud/mcp` endpoint used by the generation MCPs. The proxy's URL and access token are shown in the application's **Overview** tab after you deploy and connect the Discord account. The proxy credential is `DISCORD_BOT_TOKEN`; an AceDataCloud API token or MCP OAuth/DCR setup does not replace it.

Use a dedicated Discord account and follow Discord's current terms and rate limits. Sending, editing, deleting, and reacting affect that real account. [Deployment and API documentation](https://platform.acedata.cloud/documents/development_discord_bot?utm_source=pypi&utm_medium=referral&utm_campaign=evergreen&utm_content=discord_bot_mcp_package_quick_start).

### Local stdio setup

```bash
python -m pip install mcp-discord-bot
export DISCORD_BOT_BASE_URL='https://discord-bot-xxxxxxxxxxxx.app.acedata.cloud'
export DISCORD_BOT_TOKEN='YOUR_PROXY_TOKEN'
mcp-discord-bot
```

Copy the actual URL and token from your own application's Overview; the hostname above is only a shape example. Keep the token in your user's environment or secret store, never in a committed repo. For Claude Desktop, merge this entry into the local MCP file opened from its developer settings (`~/Library/Application Support/Claude/claude_desktop_config.json` on macOS):

```json
{
  "mcpServers": {
    "discord-bot": {
      "command": "uvx",
      "args": ["mcp-discord-bot"],
      "env": {
        "DISCORD_BOT_BASE_URL": "YOUR_DEPLOYED_PROXY_URL",
        "DISCORD_BOT_TOKEN": "YOUR_PROXY_TOKEN"
      }
    }
  }
}
```

`uvx` needs [uv](https://docs.astral.sh/uv/) on `PATH`; Claude Code, Cursor and VS Code can also launch this stdio command using their own local MCP configuration formats. Do not copy this local-process JSON into a remote connector screen.

### Verify before sending

1. Confirm the proxy application's Overview shows the Discord account **connected**. A running container alone is insufficient.
2. Call the read-only `discord_whoami` tool and check the account identity. Then use `discord_list_guilds` or `discord_list_channels` to inspect the intended target.
3. Only after confirming the destination, call a mutating tool such as `discord_send_message`. Review its output and reread the message if available. Keep the destination, content, and rate within the account's permissions.

If `discord_whoami` fails, check the proxy URL, proxy token and connected-account status. `mcp-discord-bot --transport http --port 8000` runs **your own** HTTP MCP wrapper; it is not the shared hosted OAuth service. Expose that wrapper only with appropriate network and authentication controls.

## Available Tools

| Tool | Description |
|------|-------------|
| `discord_whoami` | View the proxied Discord account details |
| `discord_list_guilds` | List all servers the account has joined |
| `discord_list_channels` | List channels in a server |
| `discord_create_text_channel` | Create a new text channel |
| `discord_list_members` | List server members |
| `discord_send_message` | Send a message (with optional reply) |
| `discord_read_messages` | Read recent messages from a channel |
| `discord_edit_message` | Edit a message you sent |
| `discord_delete_message` | Delete a message |
| `discord_search_messages` | Search for messages in a channel |
| `discord_add_reaction` | Add an emoji reaction to a message |
| `discord_pin_message` | Pin a message in a channel |
| `discord_create_dm` | Open a DM channel with a user |
| `discord_send_dm` | Send a direct message to a user |
| `discord_get_usage_guide` | Get comprehensive usage documentation |

## Documentation

<!-- canonical-documentation -->
[Documentation](https://platform.acedata.cloud/documents/development_discord_bot?utm_source=pypi&utm_medium=referral&utm_campaign=evergreen&utm_content=discord_bot_mcp_package_quick_start)

## License

MIT
