Reddit MCP Server

This MCP server allows Clients to interact with Reddit using OAuth2 authentication, enabling read-only access to search for posts within subreddits.

Features

Search posts: Search for posts within specific subreddits with various sorting options (relevance, hot, top, new, comments)
OAuth2 authentication: Secure authentication using Reddit's OAuth2 client credentials flow
Read-only access: Safe, read-only access to Reddit data without requiring user credentials

Quick Start

Create a Reddit application to get your API credentials:
- Go to https://www.reddit.com/prefs/apps
- Click "Create App" or "Create Another App"
- Choose "script" as the app type
- Note down your client ID and client secret
Add this configuration to your Claude Desktop config file:

Windows: %APPDATA%\Claude\claude_desktop_config.json
macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

{
  "mcpServers": {
    "reddit-mcp": {
      "command": "npx",
      "args": ["-y", "@enisze/reddit-mcp"],
      "env": {
        "REDDIT_CLIENT_ID": "your_client_id_here",
        "REDDIT_CLIENT_SECRET": "your_client_secret_here",
        "REDDIT_USER_AGENT": "reddit-mcp-server/1.0.0"
      }
    }
  }
}

Restart Claude Desktop

That's it! Claude can now search Reddit through the search_posts tool.

Example Usage

Try asking Claude:

"Can you search for posts about 'artificial intelligence' in the MachineLearning subreddit?"
"Search for the top 10 posts about 'Claude AI' in the artificial subreddit"
"Find recent discussions about 'programming best practices' in the programming subreddit"

Environment Variables

REDDIT_CLIENT_ID: Your Reddit app's client ID
REDDIT_CLIENT_SECRET: Your Reddit app's client secret
REDDIT_USER_AGENT: User agent string (optional, defaults to "reddit-mcp-server/1.0.0")

Development

If you want to contribute or run from source:

Clone the repository:

git clone <repository-url>
cd reddit-mcp

Install dependencies:

npm install

Build:

npm run build

Run:

npm start

Test:

# Run unit tests (no API credentials needed)
npm test

# Run API integration tests (requires Reddit credentials)
npm run test:api

Running Evaluations

To test the functionality of the Reddit MCP server:

npm run eval

This will run a series of evaluations to ensure all tools are working correctly.

Running Evals

The evals package loads an MCP client that then runs the index.ts file, so there is no need to rebuild between tests. You can load environment variables by prefixing the npx command. Full documentation can be found here.

OPENAI_API_KEY=your-key npx mcp-eval src/evals/evals.ts src/index.ts

Docker Support

You can also run this MCP server using Docker:

# Build the Docker image
docker build -t reddit-mcp .

# Run the container with environment variables
docker run -e REDDIT_CLIENT_ID=your_client_id \
           -e REDDIT_CLIENT_SECRET=your_client_secret \
           reddit-mcp

API Documentation

search_posts

Searches for posts in a Reddit subreddit using OAuth2 authentication.

Parameters:

query (string, required): Search query
subreddit (string, required): The subreddit name (without r/ prefix)
count (number, optional): Number of posts to return (1-100, default: 25)
sort (string, optional): Sort order - 'relevance', 'hot', 'top', 'new', 'comments' (default: 'relevance')

Troubleshooting

Authentication Issues

Make sure your Reddit client ID and secret are correct
Ensure your Reddit app is configured as a "script" type
Check that your user agent string is descriptive and unique

Rate Limiting

The server implements basic rate limiting (2 seconds between requests)
Reddit has its own rate limits - if you hit them, wait before retrying

Common Errors

"Subreddit not found": Check the subreddit name spelling
"OAuth2 authentication failed": Verify your Reddit app credentials
"Invalid credentials": Make sure your client ID and secret are correct

Testing

The project includes comprehensive tests to verify functionality:

Unit Tests

Run basic functionality tests without requiring Reddit API credentials:

npm test

These tests verify:

Response formatting
Type definitions
Data structure handling
Error handling logic

API Integration Tests

Test actual Reddit API functionality (requires credentials):

npm run test:api

Set up your credentials in .env first (copy from .env.example).

These tests verify:

OAuth2 authentication flow
Search functionality
API response handling
Error handling for various scenarios

See TEST.md for detailed testing instructions.

License

MIT

Reddit MCP Server

This MCP server allows Clients to interact with Reddit using OAuth2 authentication, enabling read-only access to search for posts within subreddits.

Features

Search posts: Search for posts within specific subreddits with various sorting options (relevance, hot, top, new, comments)
OAuth2 authentication: Secure authentication using Reddit's OAuth2 client credentials flow
Read-only access: Safe, read-only access to Reddit data without requiring user credentials

Quick Start

Create a Reddit application to get your API credentials:
- Go to https://www.reddit.com/prefs/apps
- Click "Create App" or "Create Another App"
- Choose "script" as the app type
- Note down your client ID and client secret
Add this configuration to your Claude Desktop config file:

Windows: %APPDATA%\Claude\claude_desktop_config.json
macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

{
  "mcpServers": {
    "reddit-mcp": {
      "command": "npx",
      "args": ["-y", "@enisze/reddit-mcp"],
      "env": {
        "REDDIT_CLIENT_ID": "your_client_id_here",
        "REDDIT_CLIENT_SECRET": "your_client_secret_here",
        "REDDIT_USER_AGENT": "reddit-mcp-server/1.0.0"
      }
    }
  }
}

Restart Claude Desktop

That's it! Claude can now search Reddit through the search_posts tool.

Example Usage

Try asking Claude:

"Can you search for posts about 'artificial intelligence' in the MachineLearning subreddit?"
"Search for the top 10 posts about 'Claude AI' in the artificial subreddit"
"Find recent discussions about 'programming best practices' in the programming subreddit"

Environment Variables

REDDIT_CLIENT_ID: Your Reddit app's client ID
REDDIT_CLIENT_SECRET: Your Reddit app's client secret
REDDIT_USER_AGENT: User agent string (optional, defaults to "reddit-mcp-server/1.0.0")

Development

If you want to contribute or run from source:

Clone the repository:

git clone <repository-url>
cd reddit-mcp

Install dependencies:

npm install

Build:

npm run build

Run:

npm start

Test:

# Run unit tests (no API credentials needed)
npm test

# Run API integration tests (requires Reddit credentials)
npm run test:api

Running Evaluations

To test the functionality of the Reddit MCP server:

npm run eval

This will run a series of evaluations to ensure all tools are working correctly.

Running Evals

OPENAI_API_KEY=your-key npx mcp-eval src/evals/evals.ts src/index.ts

Docker Support

You can also run this MCP server using Docker:

# Build the Docker image
docker build -t reddit-mcp .

# Run the container with environment variables
docker run -e REDDIT_CLIENT_ID=your_client_id \
           -e REDDIT_CLIENT_SECRET=your_client_secret \
           reddit-mcp

API Documentation

search_posts

Searches for posts in a Reddit subreddit using OAuth2 authentication.

Parameters:

query (string, required): Search query
subreddit (string, required): The subreddit name (without r/ prefix)
count (number, optional): Number of posts to return (1-100, default: 25)
sort (string, optional): Sort order - 'relevance', 'hot', 'top', 'new', 'comments' (default: 'relevance')

Troubleshooting

Authentication Issues

Make sure your Reddit client ID and secret are correct
Ensure your Reddit app is configured as a "script" type
Check that your user agent string is descriptive and unique

Rate Limiting

The server implements basic rate limiting (2 seconds between requests)
Reddit has its own rate limits - if you hit them, wait before retrying

Common Errors

"Subreddit not found": Check the subreddit name spelling
"OAuth2 authentication failed": Verify your Reddit app credentials
"Invalid credentials": Make sure your client ID and secret are correct

Testing

The project includes comprehensive tests to verify functionality:

Unit Tests

Run basic functionality tests without requiring Reddit API credentials:

npm test

These tests verify:

Response formatting
Type definitions
Data structure handling
Error handling logic

API Integration Tests

Test actual Reddit API functionality (requires credentials):

npm run test:api

Set up your credentials in .env first (copy from .env.example).

These tests verify:

OAuth2 authentication flow
Search functionality
API response handling
Error handling for various scenarios

See TEST.md for detailed testing instructions.

License

MIT