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

1. Create a Reddit application to get your API credentials:

2. 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"
      }
    }
  }
}

3. 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:

1. Clone the repository:

git clone 
cd reddit-mcp

2. Install dependencies:

npm install

3. Build:

npm run build

4. Run:

npm start

5. 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