dynamic-discord-bot-api-mcp

Production-oriented stdio MCP gateway exposing stable Discord HTTP operations that explicitly support bot-token authentication. It installs a checked-in, self-refreshing OpenAPI catalog and exposes exactly five generic tools—never one tool per endpoint.

Discord's OpenAPI specification is a public preview and may be incomplete. This project consumes only stable openapi.json; official Discord documentation remains authoritative.

Scope and architecture

Refresh filters every operation by explicit BotToken security metadata, then applies a small fail-closed classifier for OAuth, interaction-token, webhook-token, Social SDK/lobby, and ambiguous routes. It retains only transitively referenced component schemas. Excluded endpoints cannot be searched, inspected, or called.

Gateway HTTP metadata such as /gateway/bot may remain because it supports bot authentication; Gateway WebSockets and events do not. Also excluded: OAuth exchange, bearer/user authorization, self-bots, Voice WebSocket/RTP, RPC, Activities/Embedded App/Social SDKs, interaction receivers/callbacks, incoming webhook servers, webhook-token execution, preview endpoints, and arbitrary HTTP requests.

Runtime resolves one active local MCP workspace root, reloads its .env before every call, and caches a client only while security-relevant configuration is unchanged. Schema refresh uses validation, atomic rename, concurrent coalescing, and cached fallback. JSON audit events go to stderr without values or secrets.

Related MCP server: discord-mcp

Install

npm install -g dynamic-discord-bot-api-mcp
discord-bot-api-mcp

From GitHub:

npm install -g github:PrimeUpYourLife/dynamic-discord-bot-api-mcp

MCP client configuration:

{"mcpServers":{"discord":{"command":"discord-bot-api-mcp"}}}

Codex ~/.codex/config.toml:

[mcp_servers.discord]
command = "discord-bot-api-mcp"

Place DISCORD_BOT_TOKEN in active repository .env. Process environment overrides startup-directory .env; active workspace .env overrides both. Multiple, failed, non-local, or non-directory MCP roots fail closed. Catalog tools need no token.

Five tools

• discord_search_endpoints: fuzzy search IDs, methods, routes, categories, descriptions, and parameters.

• discord_get_endpoint: exact canonical ID or OpenAPI operation-ID lookup.

• discord_get_type: component-schema lookup.

• discord_call_endpoint: validate and execute a cataloged bot endpoint.

• discord_refresh_schema: fetch, filter, validate, and atomically install stable schema.

Examples:

{"search":"create message","limit":5}
{"endpoint":"create_message"}
{"endpoint":"POST /channels/{channel_id}/messages","pathParameters":{"channel_id":"123456789012345678"},"body":{"content":"Hello from MCP"}}

Upload example:

{"endpoint":"create_message","pathParameters":{"channel_id":"123456789012345678"},"body":{"content":"image"},"files":[{"path":"./uploads/image.png","filename":"image.png","contentType":"image/png"}]}

Uploads use payload_json and deterministic files[n] parts/attachment IDs. Paths resolve from active root and must remain within configured realpath roots. Base64 descriptors are also supported.

Validation separates path, query, and body values; handles required fields, nested objects, arrays, enums, nullable values, refs and unions. Snowflakes remain strings. Arrays become repeated query keys. DELETE and centrally classified destructive operations require confirm: true. Optional audit reason is percent-encoded.

Errors are structured (ENDPOINT_NOT_FOUND, ENDPOINT_NOT_ALLOWED, CONFIRMATION_REQUIRED, BOT_TOKEN_MISSING, VALIDATION_ERROR, DISCORD_API_ERROR, REQUEST_ERROR, project-root errors, or SCHEMA_REFRESH_FAILED). Discord numeric codes and nested validation errors are preserved; raw bodies, stack traces, and tokens are not.

Configuration

Use narrow production allowlists. Caller cannot supply URLs, methods, authorization, or headers. Requests always use configured base URL plus catalog route, Authorization: Bot …, and valid package User-Agent.

Discord response headers and 429 payloads control per-route/bucket and global waits; limits are not hard-coded. Fractional retry_after is honored. 429s retry within configured bound. 5xx and transport retries are limited to safe GET requests, preventing duplicate messages or moderation actions.

Development

npm ci
npm run refresh-schema
npm run check
npm test
npm run build

Tests mock network access. Daily workflow refreshes catalog and commits only generated-data changes. Manual publish workflow verifies tag/version and uses npm trusted publishing via GitHub OIDC; prereleases publish under next.