Allows browsing Reddit, searching posts and subreddits, reading comment threads and user history, managing votes, subscriptions, saved items, and inbox, and optionally posting, replying, editing, deleting, and sending messages via the Reddit API.
Click on "Install Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type @ followed by the MCP server name and your instructions, e.g., "@mcp-reddit show top posts from r/AskReddit this week"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
A Model Context Protocol server for the Reddit API — browsing, search, comment threads, user history, and (opt-in) posting.
The server is read-only by default. Mutating tools are not merely refused when writes are off — they are never registered, so an agent cannot call them at all.
Works before you log in. Reddit's anonymous installed-client grant covers subreddits, posts, comments and search, so a client id alone gets you most of this server.
Browser login as a tool. reddit_auth_login opens Reddit's consent page and catches the
callback on a loopback port — no CLI step, no password anywhere.
Comment trees are flattened and bounded. They are the single biggest context-window risk
in this API; maxDepth and maxComments are low by default and unexpanded replies are
reported, not silently dropped.
Responses are shaped. A Reddit post carries ~110 fields, most of them null or UI state. List tools return the dozen that matter plus the pagination cursor.
Rate limits surfaced. Reddit reports its budget on every response; a 429 here quotes the actual window rather than telling you to try again later.
Two transports. stdio for the usual case; Streamable HTTP with a full OAuth authorization server when you want Claude Code's Authenticate button.
Native fetch, no runtime dependencies beyond the MCP SDK and Zod (plus express in HTTP
mode, which the SDK already depends on).
Related MCP server: Reddit MCP Server
Read-only by default. REDDIT_ALLOW_WRITES=1 adds the write tools; the destructive ones
(reddit_delete, reddit_edit) and everything that publishes additionally require an
explicit confirm: true on every call.
Scopes are computed, not fixed. A read-only install never asks you to consent to posting or voting. Turning writes on requires logging in again, deliberately.
Your refresh token is written mode 0600 to ~/.config/reddit/tokens.json and never
leaves this machine. In HTTP mode it never leaves the process — the MCP client gets an opaque
local token instead.
HTTP mode binds 127.0.0.1 explicitly, caps request bodies, validates Host and
Origin, and sets header/request timeouts.
Reddit's API terms forbid automated vote manipulation, and unsolicited private messages are
the fastest route to a suspended account. reddit_vote and reddit_send_message both say so
in their descriptions, and both require confirm.
Create an app at https://www.reddit.com/prefs/apps — installed app for the login flow (no secret), or script for anonymous reads only.
Variable | Required | Description |
| yes | From the app page. Without it only the auth tools are registered. |
| web/script | Leave unset for an installed app. |
| in practice |
|
| no |
|
| no | Defaults to |
| no | Defaults to |
| no | Port for HTTP mode. Defaults to 8725. |
| no | Retry budget for 401/429/5xx. Defaults to 3. |
| no |
|
cp .env.example .envpnpm install
pnpm buildCopy .mcp.json.example to .mcp.json, fill in the client id, restart your client, then:
log me into Reddit
which calls reddit_auth_login, opens the browser, and stores a refresh token. Restart the
server afterwards to pick up the account-scoped tools.
printf '%s\n' \
'{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2024-11-05","capabilities":{},"clientInfo":{"name":"cli","version":"0"}}}' \
'{"jsonrpc":"2.0","method":"notifications/initialized"}' \
'{"jsonrpc":"2.0","id":2,"method":"tools/list"}' \
| REDDIT_CLIENT_ID=x node dist/cli.js 2>/dev/null | jq -r '.result.tools[]?.name'Always registered, even with nothing configured:
Tool | What it does | Writes |
| Credential state, active scopes, and what to set or run next | no |
| Browser login; stores a refresh token | local only |
| Forget the stored token | local only |
| Build the consent URL without listening (browser on another machine) | no |
With a client id (anonymous reads work here — no login needed):
Tool | What it does | Writes |
| Posts from a subreddit or the front page, by hot/new/top/rising | no |
| One subreddit's description, subscribers, active users | no |
| Search one subreddit or all of Reddit | no |
| One post plus its comment thread, flattened and bounded | no |
| Expand the reply stubs | no |
| An account's karma, age and flags | no |
| What an account submitted | no |
| What an account commented | no |
| Escape hatch for unwrapped endpoints (GET-only unless writes are on) | gated |
| What Reddit has said about your remaining budget | no |
After reddit_auth_login:
Tool | What it does | Writes |
| Which account this server is acting as | no |
| Subreddits you subscribe to | no |
| Your saved posts and comments | no |
| Messages, replies and mentions | no |
With REDDIT_ALLOW_WRITES=1 and a login:
Tool | What it does | Confirm |
| Submit a self or link post | yes |
| Reply to a post or comment | yes |
| Up/down/clear a vote | yes |
| Save or unsave | no |
| Join or leave a subreddit | no |
| Send a private message | yes |
| Edit your own post or comment | yes |
| Delete your own post or comment — irreversible | yes |
The default path:
reddit_search query="borrow checker" subreddit=rust sort=relevance t=all
reddit_get_post postId=<id from the search>reddit_get_post returns at most 50 comments, three levels deep. Anything it did not walk comes
back under unexpanded:
{
"post": { "id": "t3_1abc2de", "title": "…", "score": 412 },
"comments": [{ "id": "t1_x", "depth": 0, "body": "…" }],
"unexpanded": [{ "parent": "t1_x", "count": 87, "ids": ["abc", "def"] }]
}Pass those ids to reddit_get_more_comments. Re-fetching the post with a larger maxDepth
walks the same top-level branches again rather than continuing where it stopped — that is what
the stubs are for.
The Authenticate button only exists for HTTP-transport servers: OAuth in MCP is defined for HTTP
transports, and a stdio server takes its credentials from the environment. reddit_auth_login
is the stdio equivalent and is simpler. If you want the button:
pnpm dev:http # or: node dist/http.js
claude mcp add --transport http reddit http://127.0.0.1:8725/mcpRegister the callback the server prints at startup — http://127.0.0.1:8725/oauth/callback —
as the redirect URI on your Reddit app page.
Why this needs a real authorization server rather than the SDK's proxy provider.
ProxyOAuthServerProvider forwards the client's redirect_uri upstream. Reddit matches
redirect_uri byte for byte against the one value on the app page, and Claude Code picks its
loopback callback port dynamically, so the proxy's redirect is rejected every time — and Reddit
has no dynamic client registration to fall back on. So this server is its own authorization
server and hides the Reddit leg:
Claude Code → /authorize → (browser) → Reddit consent
↓
Claude Code ← /oauth/callback?code=ours ← our fixed registered callback
Claude Code → /token → our opaque token, mapped to the stored Reddit refresh tokenThe Reddit refresh token never leaves this process. Claude Code stores its own token in the macOS keychain and refreshes it automatically.
Trade-offs: the server has to already be running (an HTTP server is not spawned by the client),
and it is loopback-only by design. The upside beyond the button is that an HTTP server can be
restarted underneath a live client, so pnpm dev:http gives an edit→reload loop without
reloading the editor window.
duration=permanent or no refresh token. Omit it and Reddit issues an access token only;
the login silently stops working after an hour.
The redirect URI is matched byte for byte, which is why the loopback port is fixed rather than ephemeral.
client_id: with the trailing colon. An installed app has no secret, and Reddit rejects
Basic auth without the empty password.
Write endpoints answer HTTP 200 when the action failed. The real result is in
json.errors; a 2xx is not success. Handled centrally in client/reddit.ts.
Reddit takes form encoding on writes, never JSON.
User listings stop at ~1000 items however far you paginate, so a prolific account's full history is not reachable.
404 means banned as well as missing. A quarantined or banned subreddit is indistinguishable from a typo.
Scopes are space-separated in the authorize URL, unlike the commas Reddit uses for almost every other list.
pnpm dev # tsdown --watch
pnpm dev:http # HTTP transport with hot reload
pnpm test # vitest
pnpm typecheck
pnpm lint
pnpm formatTests run offline against a mocked fetch — no credentials, no network. The registration
matrix is asserted with toEqual, so adding a tool is always a deliberate change.
pnpm dlx release-it # bump, commit, tag
git push --follow-tags # CI publishes to npm + GHCR from the tagMIT
Sign in to Reddit in a browser. Opens Reddit's consent page, catches the callback on a loopback port and stores a refresh token, so this is a one-time step. Needed for your subscriptions, saved posts and inbox, and for anything that writes — public browsing and search already work without it.
| Name | Required | Description | Default |
|---|---|---|---|
| open | No | Open the browser automatically. Set false on a headless machine and use the returned `authorize_url` yourself. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond the annotations, the description discloses that it opens the consent page, catches the callback on a loopback port, stores a refresh token, and is a one-time step. This gives an agent an accurate model of the side effects without contradicting idempotentHint or destructiveHint.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Three tight sentences, front-loaded with the core action and followed by the behavioral and use-case context. No filler or repetition of schema content.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool with no required parameters and no output schema, the description fully covers purpose, side effects, prerequisites, and when it is needed. The parameter details are covered by the schema, so nothing important is missing for selection and invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The single 'open' parameter is already documented with 100% schema coverage, including the headless-machine case and the returned authorize_url. The description only implicitly relates to the default behavior and adds no new parameter-level semantics.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific action ('Sign in to Reddit in a browser') and describes the exact mechanism (consent page, loopback callback, refresh token). It is distinct from sibling auth tools like auth_status, auth_logout, and auth_url.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly says when login is needed — subscriptions, saved posts, inbox, and any write operation — and says public browsing/search already work without it. It does not name sibling auth alternatives explicitly, but the condition is clear.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Forget the stored Reddit refresh token. Anonymous browsing keeps working; the account-scoped tools stop. This does not revoke the app on Reddit's side — do that at https://www.reddit.com/prefs/apps.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond the annotations (destructiveHint=true, idempotentHint=true, readOnlyHint=false), the description discloses additional behavioral details: forgetting the token is destructive and irreversible from the tool's perspective, it does not revoke the app server-side, and it distinguishes between anonymous and account-scoped functionality. This provides agent-facing transparency that annotations alone do not convey.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Three sentences, each carrying clear value. The core action is front-loaded in the first sentence, followed by behavioral effects and a critical limitation with a redirect URL. No filler, redundancies, or restating of the tool name.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a zero-parameter, no-output-schema tool, the description covers all essential context: what it does, what happens afterward, what it does not do, and where to go for the complementary action. The annotations already cover idempotency and destructiveness, so nothing an agent needs to call it correctly is missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool takes zero parameters, so the input schema is trivial. The description adds meaning by explaining what entity is affected (the stored refresh token) and the scope of the action. With no parameters, the baseline is 4, and the description adequately clarifies the operation without needing to document parameter semantics.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with a specific verb and resource: 'Forget the stored Reddit refresh token.' This clearly identifies the logout action and differentiates it from siblings like reddit_auth_login and reddit_auth_status. It also specifies the operational consequence ('account-scoped tools stop'), leaving no ambiguity about what the tool does.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description clearly implies the tool is used to log out by forgetting the stored token. It provides context on effects (anonymous browsing remains, account-scoped tools stop) and an important exclusion: it does not revoke the app on Reddit's side, with an explicit pointer to the revocation URL. However, it does not explicitly name alternative sibling tools or state 'use this when you want to log out,' relying on the tool name and context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Report what credentials this server has, which tools are therefore available, and — when something is missing — exactly what to set or run to fix it. Call this first whenever a tool you expected is not there: an absent tool usually means a missing scope or login rather than a bug.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The readOnlyHint annotation already signals a safe read operation. The description adds meaningful diagnostic context: it explains the tool's role in troubleshooting missing tools and states that fixes may require setting credentials or running something, giving the agent a clearer picture of expected behavior without contradicting the annotation.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two tightly worded sentences with no filler. The first sentence states the core function, and the second provides a clear trigger condition. Every clause earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a zero-parameter diagnostic tool, the description fully covers what the tool reports, why it exists, and when to call it. No output schema exists, but the description adequately conveys that it reports credential status and remediation steps.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has zero parameters and the schema fully covers them (100% coverage). With no params, the description does not need to explain parameter semantics; the baseline of 4 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Uses a specific verb ('Report') with a clear resource: the server's credentials and resulting tool availability. It also explains the diagnostic purpose and distinguishes itself from the auth action siblings (login/logout/url) by focusing on status rather than performing authentication.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Gives explicit, actionable guidance: 'Call this first whenever a tool you expected is not there.' It also explains the reasoning — an absent tool usually indicates a missing scope or login rather than a bug — which helps the agent decide when this tool is appropriate.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Build the Reddit consent URL without starting the loopback listener. Use this when the browser is on a different machine than the server, or to check which scopes a login would request before running reddit_auth_login.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The readOnlyHint annotation already signals a safe read-only operation, and the description adds important behavioral context by clarifying that the tool does not start the loopback listener. This meaningfully informs an agent about side effects beyond what the annotation alone conveys.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences with no wasted words, front-loading the core function and then adding the practical use cases. Every sentence contributes essential selection and invocation information.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a zero-parameter, read-only URL-building tool, the description covers what it does, what it does not do, and when to use it. No output schema exists, but the phrase 'Build the Reddit consent URL' sufficiently conveys the expected result, making the definition complete for invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has zero parameters and 100% schema description coverage, so there is no parameter gap to compensate for. The description appropriately focuses on behavior and usage rather than parameter details.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb ('Build') and resource ('Reddit consent URL'), and explicitly distinguishes this tool from reddit_auth_login by noting it does not start the loopback listener. This makes its purpose immediately unambiguous and differentiates it from the closely related authentication sibling.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives explicit when-to-use guidance: when the browser is on a different machine than the server, or to check which scopes a login would request before running reddit_auth_login. It also names the alternative tool, leaving no ambiguity about selection.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Expand the reply stubs reddit_get_post reported under unexpanded. Pass the post id and the ids from one stub. This is the only way to reach a deep thread's tail — re-fetching the post with a bigger maxDepth walks the same top-level branches again rather than continuing where it stopped.
| Name | Required | Description | Default |
|---|---|---|---|
| postId | Yes | A post id. Accepts the bare id ("1abc2de"), the fullname ("t3_1abc2de") or the full permalink — they are normalized for you. | |
| commentIds | Yes | Comment ids from an `unexpanded[].ids` array, up to 100 per call. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, so no contradiction exists. The description adds meaningful behavioral context beyond that: it can reach the tail of a deep thread and specifically continues where the previous fetch stopped, while re-fetching repeats top-level branches. It does not describe response shape or error behavior, but the core behavior is well disclosed.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is three sentences with no filler. The action is front-loaded, the required inputs are stated immediately, and the final sentence explains the tool's unique value without repeating schema details.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a two-parameter read-only tool, the description is nearly complete: it defines the source data, the invocation inputs, and the limitation of the alternative. There is no output schema, and the description does not describe the return format, but the operation is simple and the context is strong enough for an agent to invoke it correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so the baseline is 3. The description adds value by emphasizing that the ids must come from one unexpanded stub, reinforcing a constraint not fully explicit in the schema, and by linking both parameters to the workflow described in reddit_get_post.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb and resource: 'Expand the reply stubs reddit_get_post reported under `unexpanded`.' It directly states what the tool does and clearly differentiates it from reddit_get_post, so an agent can recognize its distinct role.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly tells the agent when to use this tool: after reddit_get_post returns unexpanded stubs, pass the post id and ids from one stub. It also explains why the alternative of re-fetching with a larger maxDepth will not work, making the selection guidance unambiguous.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get one post together with its comment thread, flattened to a depth-tagged list. Comment trees are the largest thing this API returns, so maxComments and maxDepth are deliberately low: raise them when you actually need the long tail. Replies that were not expanded are reported under unexpanded with their ids, so nothing is dropped silently — pass those ids to reddit_get_more_comments.
| Name | Required | Description | Default |
|---|---|---|---|
| sort | No | Comment ordering. `confidence` is Reddit's default 'best'. | confidence |
| postId | Yes | A post id. Accepts the bare id ("1abc2de"), the fullname ("t3_1abc2de") or the full permalink — they are normalized for you. | |
| maxDepth | No | How deep to walk reply chains (0-10). Defaults to 3. | |
| maxComments | No | Stop after this many comments (1-500). Defaults to 50. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond the readOnlyHint annotation, the description adds valuable behavioral context: the output is a flattened depth-tagged list, comment trees are the largest API response, limits are deliberately conservative, and unexpanded replies are preserved under `unexpanded` with ids so nothing is silently dropped. This meaningfully enriches what the agent can expect from the call.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Three sentences, no filler. The core action leads, then the single most important behavioral caveat, then the related-tool handoff. Every sentence earns its place and the structure is easy to scan.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a read-only tool with full schema coverage and no output schema, the description supplies enough context: what comes back (flattened depth-tagged list), how limits behave, how truncation is surfaced, and where to continue. No critical information for correct invocation is missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so the baseline is 3. The description adds practical parameter guidance above the schema by explaining that maxComments and maxDepth default low intentionally and should be raised only for deep/long-tail needs, plus how unexpanded replies map to further calls. It does not enhance all parameters, but it compensates for the more subtle ones.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a precise verb and resource: 'Get one post together with its comment thread, flattened to a depth-tagged list.' It clearly differentiates from sibling tools like reddit_get_more_comments by describing how unexpanded replies are handled, leaving no ambiguity about what reddit_get_post is for.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly tells the agent when to raise maxComments and maxDepth ('raise them when you actually need the long tail') and routes leftover replies to a specific alternative: 'pass those ids to reddit_get_more_comments.' This is explicit when/alternative guidance rather than merely implied context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get one subreddit's description, subscriber count and current active users. Useful before listing posts, to confirm the name is right and the community is the one you meant — Reddit returns 404 for both a misspelling and a banned subreddit.
| Name | Required | Description | Default |
|---|---|---|---|
| subreddit | Yes | Subreddit name without the `r/` prefix, e.g. "rust". |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already provide readOnlyHint=true, and the description adds meaningful behavioral context: the 404 ambiguity between misspellings and banned subreddits, and what information the tool returns. This goes beyond the structured annotation without contradicting it.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two tightly written sentences with zero fluff. The core purpose is front-loaded, and the usage guidance follows naturally. Every sentence earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple single-parameter read tool with readOnlyHint, the description covers what is returned and the key edge case (404 behavior). No output schema exists, but the description adequately summarizes the return content, making it complete enough for an agent to invoke correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema already fully documents the parameter with pattern and example, achieving 100% schema description coverage. The description does not add parameter-specific meaning beyond what the schema provides, so baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb ('Get'), the resource ('subreddit'), and the exact data returned ('description, subscriber count and current active users'). It also distinguishes itself from siblings by positioning it as a pre-listing check, which differentiates it from reddit_list_posts and reddit_search.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives a clear use case ('Useful before listing posts, to confirm the name is right and the community is the one you meant'). It does not explicitly name alternative tools, but the context makes it clear when to use this tool versus listing or searching.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get a Reddit account's karma, age and flags. Works for any public account without a login. Suspended and shadowbanned accounts return 404, not an empty profile.
| Name | Required | Description | Default |
|---|---|---|---|
| username | Yes | Reddit username without the `u/` prefix, e.g. "spez". |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With readOnlyHint=true already in annotations, the description adds meaningful behavioral context: no login needed, works for any public account, and suspended/shadowbanned accounts return 404 instead of an empty profile. This error-handling disclosure goes well beyond what annotations convey and helps the agent interpret results correctly.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences with zero filler. The first sentence states the core function, and the second handles auth and edge-case behavior. Every clause earns its place and the most important information is front-loaded.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a one-parameter read-only tool, this description is nearly complete: it names the output fields (karma, age, flags), clarifies auth requirements, and covers error behavior. The only slight gap is that 'flags' is loosely defined and the exact response shape is not described, but no output schema is provided and the description still gives enough for an agent to know what to expect.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Input schema coverage is 100%, including a description explaining 'Reddit username without the `u/` prefix, e.g. "spez".' The tool description does not add further parameter-specific detail, but the schema already fully defines the only parameter. Baseline 3 is appropriate because the description neither detracts from nor enhances the schema's high coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description starts with a specific verb and resource: 'Get a Reddit account's karma, age and flags.' It clearly identifies the account-level scope, which distinguishes it from sibling tools like reddit_get_post, reddit_get_subreddit, reddit_list_user_posts, and reddit_list_user_comments. The mention of 'account' makes the purpose unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description states a clear usage condition: 'Works for any public account without a login.' This tells the agent that no authentication is needed and the tool is broadly applicable. It does not explicitly name alternatives or state when not to use this tool, but the context is clear enough for selection among siblings.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List posts from a subreddit, or from the site-wide front page when subreddit is omitted. Returns each post's id, title, author, score, comment count and permalink — the body text or link, but never the comments. Use reddit_get_post for one thread's discussion; fetching 25 posts' comment trees is orders of magnitude more text than this.
| Name | Required | Description | Default |
|---|---|---|---|
| sort | No | Listing sort. `top` and `controversial` also read `time`. | hot |
| time | No | Time window, used only by the `top` and `controversial` sorts. Ignored otherwise. | day |
| after | No | Pagination cursor: pass the `after` value from the previous response to get the next page. Reddit paginates by fullname, not by offset, so there is no page number. | |
| limit | No | How many items to return (1-100). Defaults to 25; Reddit's hard cap is 100. | |
| subreddit | No | Subreddit name without the `r/` prefix, e.g. "rust". |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The annotations only declare readOnlyHint=true, so the description carries the burden of behavioral context. It adds the front-page fallback when subreddit is omitted, the exact return fields, and a firm exclusion: 'the body text or link, but never the comments.' This is meaningful beyond annotations, though it could add rate-limit or auth caveats.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Three sentences with no filler. It front-loads the core scope and return shape, then closes with the alternative-routing advice. Every sentence earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
All five parameters are fully documented in the schema, the read-only annotation covers safety, and the description covers scope, return shape, exclusions, and the primary sibling distinction. There is no output schema, but the return-field list fills that gap. Nothing needed to invoke it correctly is missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the baseline is 3. The description adds the subreddit-omitted front-page behavior and the body/link-vs-comments distinction, but it does not need to re-explain sort, time, pagination, or limit because the schema already does so.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with a specific verb and resource: 'List posts from a subreddit, or from the site-wide front page when `subreddit` is omitted.' It enumerates the returned fields and explicitly contrasts with reddit_get_post, so an agent can distinguish this tool from its siblings without inspecting schemas.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
It explicitly names reddit_get_post as the alternative for 'one thread's discussion' and gives the reason: fetching 25 posts' comment trees is orders of magnitude more text. This is a clear routing rule for the main ambiguity. It doesn't mention every sibling, but the primary alternative is resolved.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List the comments an account has written. Same ~1000-item ceiling as reddit_list_user_posts. Each comment carries its parent id, so you can follow one back to its thread with reddit_get_post.
| Name | Required | Description | Default |
|---|---|---|---|
| sort | No | Listing sort. `top` and `controversial` also read `time`. | hot |
| time | No | Time window, used only by the `top` and `controversial` sorts. Ignored otherwise. | day |
| after | No | Pagination cursor: pass the `after` value from the previous response to get the next page. Reddit paginates by fullname, not by offset, so there is no page number. | |
| limit | No | How many items to return (1-100). Defaults to 25; Reddit's hard cap is 100. | |
| username | Yes | Reddit username without the `u/` prefix, e.g. "spez". |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already provide readOnlyHint=true, so the safety profile is covered. The description adds useful behavioral facts beyond the schema: the ~1000-item pagination ceiling shared with reddit_list_user_posts, and the presence of a parent id on each comment that enables thread lookup. It doesn't detail output shape or auth, but the annotation lowers that burden.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences with no filler. The core purpose is front-loaded, and the second sentence adds two genuinely useful facts (ceiling and parent-id linkage) without repeating schema content.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With 5 parameters, full schema coverage, and readOnlyHint, the definition is sufficient for selecting and invoking the tool: it states the resource, the pagination ceiling, and how to connect a result to reddit_get_post. It is slightly light on return-value structure, but no output schema is present and the parent-id clue is actionable.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%; every parameter (sort, time, after, limit, username) already has a meaningful description, enums, defaults, or constraints. The tool description adds no parameter-level detail beyond what the schema provides, so the baseline of 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with a concrete verb ('List'), a clear object ('comments'), and a scope qualifier ('an account has written'). This makes it immediately distinguishable from sibling reddit_list_user_posts, and the reference to reddit_get_post frames what the result is for.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The intended use case — listing a user's comment history — is clear, and the parent-id note gives an explicit follow-up path to reddit_get_post. It does not state an explicit 'use X instead' or when-not-to-use condition, but the tool's scope is obvious enough to route an agent.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List the posts an account has submitted, newest first by default. Reddit only serves roughly the last 1000 items of any user listing however far you paginate, so this cannot reconstruct a full history for a prolific account.
| Name | Required | Description | Default |
|---|---|---|---|
| sort | No | Listing sort. `top` and `controversial` also read `time`. | hot |
| time | No | Time window, used only by the `top` and `controversial` sorts. Ignored otherwise. | day |
| after | No | Pagination cursor: pass the `after` value from the previous response to get the next page. Reddit paginates by fullname, not by offset, so there is no page number. | |
| limit | No | How many items to return (1-100). Defaults to 25; Reddit's hard cap is 100. | |
| username | Yes | Reddit username without the `u/` prefix, e.g. "spez". |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description adds a valuable non-obvious behavior beyond the readOnlyHint: Reddit only serves roughly the last 1000 items and full history cannot be reconstructed. However, the claim 'newest first by default' conflicts with the schema's declared default of 'hot' for the sort parameter, which misleads the agent about actual default behavior.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences with no filler. The first gives the core action and resource; the second delivers an important limitation. Information is front-loaded and every sentence earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a read-only listing tool with a well-documented schema, the description covers the essential purpose, ordering default, and the critical 1000-item pagination ceiling. The main gap is the contradictory default ordering statement, which forces the agent to resolve the mismatch between description and schema.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% and all five parameters are thoroughly documented with enums, defaults, and constraints, so the baseline is 3. The description contributes no additional parameter-level guidance and actually introduces conflict by saying 'newest first by default' while the schema default for sort is 'hot'.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the action ('List the posts'), the resource ('an account has submitted'), and a key ordering detail ('newest first by default'). This readily distinguishes it from sibling tools like reddit_list_user_comments (comments) or reddit_get_post (single post).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
It gives clear context for when this tool is appropriate: listing posts submitted by a specific account. The 1000-item limitation also usefully tells agents when pagination cannot recover full history. However, it does not explicitly name alternative tools or state when not to use it, so it falls short of a 5.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Report what Reddit has said about your remaining budget on each endpoint used so far this session. Reddit allows roughly 100 requests per minute per OAuth client; check here before a large paginated read rather than after a 429.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already provide readOnlyHint, and the description adds meaningful context by clarifying that results are scoped to endpoints used this session and reflect Reddit's communicated budget. It also explains the roughly 100-requests-per-minute constraint, which helps the agent understand the check's purpose.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two dense sentences front-load the tool's purpose and then immediately provide actionable usage guidance. Every clause adds value; there is no filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a read-only, zero-parameter status tool, the description covers purpose, scope, and when to invoke it. Since there is no output schema, a more specific statement about the return shape would be a minor improvement, but it is not necessary for correct invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
There are zero parameters and the input schema is empty, so the baseline is 4. The description's session and endpoint scoping is sufficient context for a parameterless call.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with 'Report what Reddit has said about your remaining budget on each endpoint used so far this session,' which is a specific verb plus a clear resource. It is distinctly different from sibling tools like reddit_auth_status or reddit_request.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives explicit timing guidance: 'check here before a large paginated read rather than after a 429.' It does not explicitly name alternative tools or exclusion conditions, so it stops just short of full when/when-not coverage.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Call any Reddit API endpoint directly, for the many endpoints this server does not wrap. Paths are relative to https://oauth.reddit.com — e.g. /r/rust/about/rules. The response is returned raw and unshaped, so keep limit small: an unshaped listing is roughly ten times the size of what the other tools return. Writes are DISABLED: only GET is permitted. Set REDDIT_ALLOW_WRITES=1 and sign in to allow POST.
| Name | Required | Description | Default |
|---|---|---|---|
| form | No | Form fields for a POST. Reddit takes form encoding, never JSON. | |
| path | Yes | Path below the API root, starting with "/", e.g. "/r/rust/about/rules". | |
| query | No | Query parameters for a GET. | |
| asUser | No | Send with the signed-in user's token rather than the anonymous app token. Required for anything under /api/v1/me, /message or /subreddits/mine. | |
| method | No | HTTP method. | GET |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description adds important behavioral context beyond the readOnlyHint annotation: responses are raw and unshaped, listings are roughly ten times larger, writes are disabled by default, and POST can be enabled via an environment variable. This is exactly the kind of non-obvious runtime behavior an agent needs to know. The mention of POST is inconsistent with the schema's method enum, but not with the annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Four sentences, each earning its place: purpose, path example, response-size warning, and write policy. The most important routing information is front-loaded.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a passthrough tool with no output schema, it covers the key risks: raw response size, write restrictions, and path format. However, the description's claim that POST can be enabled conflicts with the schema's method enum, which only permits GET; this could confuse an agent trying to invoke the advertised POST capability.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the baseline is 3. The description's example path and the 'keep limit small' warning add some practical context, but it does not meaningfully enhance the parameter-level semantics already present in the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with a clear verb and resource: 'Call any Reddit API endpoint directly, for the many endpoints this server does not wrap.' This immediately distinguishes it from the wrapped sibling tools and explains its role as a passthrough for the rest of the Reddit API.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
It clearly states when to use it — for endpoints the server does not wrap — and includes operational guidance about raw responses and write restrictions. It does not explicitly name alternatives, but the phrase 'this server does not wrap' implies the sibling tools should be preferred for covered endpoints.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Search Reddit. Scoped to one subreddit when subreddit is given, site-wide otherwise. Reddit's index is weaker than a web search engine's: prefer a few distinctive words over a natural-language question, and note that sort=relevance over time=all is usually better than new for finding the canonical thread.
| Name | Required | Description | Default |
|---|---|---|---|
| sort | No | Result ordering. `comments` sorts by comment count. | relevance |
| time | No | Time window, used only by the `top` and `controversial` sorts. Ignored otherwise. | day |
| after | No | Pagination cursor: pass the `after` value from the previous response to get the next page. Reddit paginates by fullname, not by offset, so there is no page number. | |
| limit | No | How many items to return (1-100). Defaults to 25; Reddit's hard cap is 100. | |
| query | Yes | Search terms. Supports Reddit operators like `author:spez` and `flair:"help"`. | |
| subreddit | No | Subreddit name without the `r/` prefix, e.g. "rust". |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already mark the tool as read-only, so the description doesn't need to cover safety. It adds useful behavioral context beyond the annotation by explaining that Reddit's search index is weaker than web search engines and that relevance/time=all typically outperforms `new` for canonical threads. It doesn't discuss return format, but that's a minor gap for a read-only search tool.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Three concise sentences with no filler: the action and scope are first, followed by two high-value search-strategy tips. Every sentence earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a read-only search tool with six well-documented params, the description covers the essential decisions: scope, query style, and sort/time strategy. There is no output schema, so return-format details are not explicit, but the sibling tools and the parameter descriptions provide enough surrounding context for correct invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so the baseline is 3. The description adds value beyond the schema by advising query formulation ('a few distinctive words over a natural-language question') and by clarifying the interaction of `sort` and `time` for the canonical-thread use case. This goes beyond the raw parameter definitions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description opens with the specific action and resource, 'Search Reddit,' and immediately clarifies the scope behavior: subreddit-specific when `subreddit` is provided, site-wide otherwise. This also distinguishes it from sibling listing/getting tools, which are about browsing or retrieving posts rather than searching.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives clear invocation guidance: provide `subreddit` for scoped search and use distinctive keywords rather than natural-language queries. It also advises on `sort` and `time` settings for finding the canonical thread, but it does not explicitly name alternative sibling tools or state when not to use this tool.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Each tool targets a distinct resource or action: auth login/logout/url/status, user profiles, post listings, search, post+comments, more comments, raw API access, and rate-limit status are clearly separated. Even the two status tools are differentiated by whether they report credentials or API budget.
All tools use the same snake_case reddit_ prefix and follow a predictable action-oriented pattern: get_*, list_*, auth_*, and status/request. There is no mixing of naming styles or confusing verbs.
14 tools is well within the ideal range for a Reddit client. The count is substantial enough to cover auth, users, posts, comments, subreddits, search, and raw access without feeling bloated or redundant.
The read-side surface is strong: posts, comments, users, subreddits, search, pagination, and auth are all covered. The raw reddit_request tool fills many gaps, but there are no dedicated write tools or convenience wrappers for account-scoped features like subscriptions, saved posts, or inbox despite auth_login mentioning them.
Unclaimed servers have limited discoverability.
If you are the server author, to access and configure the admin panel.
Browse and manage Reddit posts, comments, and threads. Fetch user activity, explore hot/new/rising…
Read-only Reddit search API for AI agents: posts, comments, comment trees, subreddit rules.
Reddit MCP server: search posts, subreddit feeds, comments & user profiles as JSON. No API key.
Reddit MCP — public Reddit data via JSON endpoints (no auth required)
We provide all the information about MCP servers via our MCP API.
curl -X GET 'https://glama.ai/api/mcp/v1/servers/mgcrea/mcp-reddit'
If you have feedback or need assistance with the MCP directory API, please join our Discord server