samy-clivolt/reddit-mcp-server

Reddit MCP Server 🚀

A powerful Model Context Protocol (MCP) server that provides comprehensive tools for fetching, analyzing, and creating Reddit content. Built with TypeScript and designed for seamless integration with AI assistants like Claude Desktop and Cursor.

🌟 Features

📖 Read-Only Tools (Client Credentials Only)

• User Analysis: get_user_info, get_user_posts, get_user_comments, get_user_activity
• Content Discovery: get_top_posts, search_posts, search_subreddits
• Subreddit Insights: get_subreddit_info, get_trending_subreddits
• Direct Access: get_comment, get_submission, get_comments_by_submission

✍️ Write Tools (User Authentication Required)

• Content Creation: create_post - Create optimized posts with engagement insights
• Community Engagement: reply_to_post - Add thoughtful replies with context analysis

🚀 Quick Start

Prerequisites

• Node.js 18+
• npm or yarn
• Reddit API credentials

Installation

1. Clone the repository

git clone https://github.com/yourusername/reddit-mcp-server.git
cd reddit-mcp-server

2. Install dependencies

npm install

3. Set up Reddit API credentials

   • Go to Reddit App Preferences
   • Click "Create App" or "Create Another App"
   • Select "script" as application type
   • Fill in the required information
   • Copy your Client ID and Client Secret

4. Configure environment variables

cp .env.example .env
# Edit .env with your Reddit API credentials

5. Build and test

npm run build
npm run dev

🔧 Configuration

Environment Variables

Create a .env file in the root directory:

# Required: Reddit API Configuration
REDDIT_CLIENT_ID=your_client_id_here
REDDIT_CLIENT_SECRET=your_client_secret_here
REDDIT_USER_AGENT=RedditMCPServer/1.0.0

# Optional: For write operations (posts, comments)
REDDIT_USERNAME=your_reddit_username
REDDIT_PASSWORD=your_reddit_password

Operating Modes

🔍 Read-Only Mode

• Required: CLIENT_ID, CLIENT_SECRET, USER_AGENT
• Capabilities: Search, read posts, analyze users and subreddits
• Limitations: Cannot create posts or comments

📝 Full Mode

• Required: All credentials above
• Capabilities: All read operations + post creation and commenting

🛠️ Integration with AI Assistants

Claude Desktop / Cursor Configuration

Add this to your MCP configuration file:

{
  "mcpServers": {
    "reddit": {
      "command": "node",
      "args": ["/path/to/reddit-mcp-server/build/index.js"],
      "env": {
        "REDDIT_CLIENT_ID": "your_client_id",
        "REDDIT_CLIENT_SECRET": "your_client_secret",
        "REDDIT_USER_AGENT": "RedditMCPServer/1.0.0",
        "REDDIT_USERNAME": "your_username",
        "REDDIT_PASSWORD": "your_password"
      },
      "autoApprove": [
        "test_reddit_mcp_server",
        "get_reddit_post",
        "get_top_posts",
        "get_user_info",
        "get_subreddit_info",
        "get_trending_subreddits",
        "get_comment",
        "get_comments_by_submission",
        "get_submission",
        "get_subreddit",
        "search_posts",
        "search_subreddits",
        "get_user_posts",
        "get_user_comments",
        "get_user_activity",
        "create_post",
        "reply_to_post"
      ]
    }
  }
}

📚 Available Tools

User Analysis

• get_user_info(username) - Comprehensive user profile analysis with engagement insights
• get_user_posts(username, sort?, limit?) - User's post history with sorting options
• get_user_comments(username, sort?, limit?) - User's comment history with analysis
• get_user_activity(username, limit?) - Complete activity analysis and patterns

Content Discovery

• get_top_posts(subreddit, time_filter?, limit?) - Top posts from subreddit with time filtering
• search_posts(subreddit, query, sort?, limit?) - Advanced search within specific subreddits
• search_subreddits(query, limit?) - Discover subreddits by name or description

Subreddit Tools

• get_subreddit_info(subreddit_name) - Detailed subreddit analysis and community insights
• get_trending_subreddits() - Currently trending subreddits across Reddit

Direct Access

• get_comment(comment_id) - Retrieve specific comment with detailed analysis
• get_submission(submission_id) - Complete submission details with metadata
• get_comments_by_submission(submission_id, limit?) - All comments from a specific post

Content Creation (Requires Authentication)

• create_post(subreddit, title, content, is_self?) - Create new posts with optimization
• reply_to_post(post_id, content, subreddit?) - Reply to existing posts with context

🧪 Testing

Test your configuration:

# Build the project
npm run build

# Start development server with inspector
npm run dev

# Run in production mode
npm start

The development server will start an inspector at http://127.0.0.1:6274/ where you can test all tools interactively.

🔒 Security & Privacy

• ✅ Environment variables are properly configured in .gitignore
• ✅ No credentials are hardcoded in the source code
• ✅ Secure Reddit API authentication flow
• ✅ Read-only mode available for enhanced security
• ✅ Comprehensive input validation and error handling

📦 Dependencies

• @modelcontextprotocol/sdk: ^1.11.3 - MCP protocol implementation
• axios: ^1.9.0 - HTTP client for Reddit API interactions
• dotenv: ^16.5.0 - Environment variable management
• TypeScript: ^5.8.3 - Type-safe development environment

🤝 Contributing

We welcome contributions! Please follow these steps:

1. Fork the repository
2. Create a feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

📄 License

This project is licensed under the ISC License - see the file for details.

🙏 Acknowledgments

• Inspired by the Python Reddit MCP Server by Arindam200
• Built following Eugene Sh's MCP Server Tutorial
• Extended with additional tools for enhanced Reddit interaction capabilities
• Thanks to the MCP community for feedback and contributions

📞 Support

If you encounter any issues or have questions:

1. Check the Issues page
2. Create a new issue with detailed information about your problem
3. Include your environment details and error messages
4. Join the discussion in our community

🚀 Roadmap

• Add support for Reddit's new API features
• Implement caching for improved performance
• Add more advanced analytics tools
• Support for Reddit Collections
• Enhanced error handling and retry mechanisms

Made with ❤️ for the MCP community

Star this repository if you find it useful!