discord-mcp

Read messages

discord_read_messages

Read-only

Toolset
Messages messages
Discord permissions
View Channel and Read Message History
Context cost
981 tokens, estimated3,923 bytes of definition, divided by 4

Read messages from a text channel or thread, oldest-to-newest. Page backwards by re-calling with before set to the id of the oldest message you received, which walks a channel past the 100-message per-call cap. Requires the View Channel and Read Message History permissions; without Read Message History an empty result fails with an error naming the permission. Returns { messages: [...] } with id, author, content, timestamp, attachment count, pinned flag, and the text of any embeds. Use discord_search_messages or discord_search_guild_messages to filter by keyword, or discord_fetch_pinned_messages for pinned messages only.

Risk and annotations

Read-onlyreadOnlyHintyesDoes not modify your server.
DestructivedestructiveHintn/aNot declared: it only applies to tools that write.
IdempotentidempotentHintn/aNot declared.
Open worldopenWorldHintyesInteracts with an external system: Discord.

Annotations are hints the server declares. Clients use them to decide when to ask you before a call.

Parameters

ParameterTypeRulesDescription
channel_idrequiredstring
pattern ^\d{17,20}$
ID (snowflake) of the channel or thread to read from.
limitoptionalinteger
1 to 100default 20
How many messages to fetch per call (1–100). Default 20.
beforeoptionalstring
pattern ^\d{17,20}$
Return only messages older than this message ID (snowflake). Page backwards through history by passing the id of the oldest message from the previous call.
afteroptionalstring
pattern ^\d{17,20}$
Return only messages newer than this message ID (snowflake). Page forwards by passing the id of the newest message from the previous call.
aroundoptionalstring
pattern ^\d{17,20}$
Return messages centered on this message ID (snowflake): Discord splits `limit` either side of it, and an even `limit` puts the extra message on the newer side. Use it to read outward from a known message, such as a discord_search_guild_messages hit.
sinceoptionalstring
string:format date
pattern (203 characters)^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))$
string:format date-time
pattern (288 characters)^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d:[0-5]\d(?:\.\d+)?(?:Z|([+-](?:[01]\d|2[0-3]):[0-5]\d)))$
Return only messages posted after this instant, as an ISO 8601 date or a date-time with an explicit offset (e.g. "2026-08-01" or "2026-08-01T09:00:00Z"). Convenience form of `after`: the call yields the oldest `limit` messages after that instant, so page forwards with `after` set to the newest id received.

Output

Declared by outputSchema: clients receive this shape as structuredContent.

FieldTypeDescription
guild_idrequiredstring or null
messagesrequiredarray of objects
id (nested, level 1)requiredstring
author (nested, level 1)requiredstring
author_id (nested, level 1)requiredstring
webhook_id (nested, level 1)string
content (nested, level 1)requiredstring
timestamp (nested, level 1)requiredstring
embeds (nested, level 1)array of objects
title (nested, level 2)string
author (nested, level 2)string
description (nested, level 2)string
url (nested, level 2)string
fields (nested, level 2)array of objects
name (nested, level 3)requiredstring
value (nested, level 3)requiredstring
moreFields (nested, level 2)numberCount of fields left out past the first 10. Absent when none were.
footer (nested, level 2)string
attachments (nested, level 1)requirednumber
pinned (nested, level 1)requiredboolean

Related tools

Named in its description

Also in Messages

Raw definition (3,923 bytes)
{
  "name": "discord_read_messages",
  "description": "Read messages from a text channel or thread, oldest-to-newest. Page backwards by re-calling with before set to the id of the oldest message you received, which walks a channel past the 100-message per-call cap. Requires the View Channel and Read Message History permissions; without Read Message History an empty result fails with an error naming the permission. Returns { messages: [...] } with id, author, content, timestamp, attachment count, pinned flag, and the text of any embeds. Use discord_search_messages or discord_search_guild_messages to filter by keyword, or discord_fetch_pinned_messages for pinned messages only.",
  "inputSchema": {
    "type": "object",
    "properties": {
      "channel_id": {
        "type": "string",
        "pattern": "^\\d{17,20}$",
        "description": "ID (snowflake) of the channel or thread to read from."
      },
      "limit": {
        "default": 20,
        "description": "How many messages to fetch per call (1–100). Default 20.",
        "type": "integer",
        "minimum": 1,
        "maximum": 100
      },
      "before": {
        "type": "string",
        "pattern": "^\\d{17,20}$",
        "description": "Return only messages older than this message ID (snowflake). Page backwards through history by passing the id of the oldest message from the previous call."
      },
      "after": {
        "type": "string",
        "pattern": "^\\d{17,20}$",
        "description": "Return only messages newer than this message ID (snowflake). Page forwards by passing the id of the newest message from the previous call."
      },
      "around": {
        "type": "string",
        "pattern": "^\\d{17,20}$",
        "description": "Return messages centered on this message ID (snowflake): Discord splits `limit` either side of it, and an even `limit` puts the extra message on the newer side. Use it to read outward from a known message, such as a discord_search_guild_messages hit."
      },
      "since": {
        "anyOf": [
          {
            "type": "string",
            "format": "date",
            "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))$"
          },
          {
            "type": "string",
            "format": "date-time",
            "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"
          }
        ],
        "description": "Return only messages posted after this instant, as an ISO 8601 date or a date-time with an explicit offset (e.g. \"2026-08-01\" or \"2026-08-01T09:00:00Z\"). Convenience form of `after`: the call yields the oldest `limit` messages after that instant, so page forwards with `after` set to the newest id received."
      }
    },
    "required": [
      "channel_id"
    ],
    "additionalProperties": false
  },
  "outputSchema": {
    "type": "object",
    "properties": {
      "guild_id": {
        "type": [
          "string",
          "null"
        ]
      },
      "messages": {
        "type": "array",
        "items": {
          "type": "object",
          "properties": {
            "id": {
              "type": "string"
            },
            "author": {
              "type": "string"
            },
            "author_id": {
              "type": "string"
            },
            "webhook_id": {
              "type": "string"
            },
            "content": {
              "type": "string"
            },
            "timestamp": {
              "type": "string"
            },
            "embeds": {
              "type": "array",
              "items": {
                "type": "object",
                "properties": {
                  "title": {
                    "type": "string"
                  },
                  "author": {
                    "type": "string"
                  },
                  "description": {
                    "type": "string"
                  },
                  "url": {
                    "type": "string"
                  },
                  "fields": {
                    "type": "array",
                    "items": {
                      "type": "object",
                      "properties": {
                        "name": {
                          "type": "string"
                        },
                        "value": {
                          "type": "string"
                        }
                      },
                      "required": [
                        "name",
                        "value"
                      ],
                      "additionalProperties": false
                    }
                  },
                  "moreFields": {
                    "description": "Count of fields left out past the first 10. Absent when none were.",
                    "type": "number"
                  },
                  "footer": {
                    "type": "string"
                  }
                },
                "additionalProperties": false
              }
            },
            "attachments": {
              "type": "number"
            },
            "pinned": {
              "type": "boolean"
            }
          },
          "required": [
            "id",
            "author",
            "author_id",
            "content",
            "timestamp",
            "attachments",
            "pinned"
          ],
          "additionalProperties": false
        }
      }
    },
    "required": [
      "guild_id",
      "messages"
    ],
    "additionalProperties": false
  },
  "annotations": {
    "title": "Read messages",
    "readOnlyHint": true,
    "openWorldHint": true
  }
}