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.

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

Variable	Default	Meaning
DISCORD_BOT_TOKEN	unset	Bot token; calls fail safely when absent
DISCORD_API_BASE_URL	https://discord.com/api/v10	Fixed API origin
DISCORD_ENDPOINT_ALLOWLIST	*	Comma-separated IDs/operation IDs with * globs
DISCORD_REQUEST_TIMEOUT_MS	30000	Per-attempt timeout
DISCORD_REQUEST_RETRIES	2	Retry count
DISCORD_RATE_LIMIT_PER_SECOND	45	Local global safety rate
DISCORD_RATE_LIMIT_BURST	50	Local burst
DISCORD_SCHEMA_MAX_AGE_HOURS	24	Refresh threshold
DISCORD_SCHEMA_PATH	bundled catalog	Alternate catalog path
DISCORD_LOCAL_FILE_ROOTS	active root	Platform-delimited upload roots
DISCORD_MAX_UPLOAD_BYTES	10485760	Per-file limit
DISCORD_ALLOW_UNKNOWN_PARAMETERS	false	Validation escape hatch
LOG_LEVEL	info	debug, info, warn, error

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.