README.md•7.5 kB
# 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.
[](https://opensource.org/licenses/ISC)
[](https://nodejs.org/)
[](https://www.typescriptlang.org/)
## 🌟 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**
```bash
git clone https://github.com/yourusername/reddit-mcp-server.git
cd reddit-mcp-server
```
2. **Install dependencies**
```bash
npm install
```
3. **Set up Reddit API credentials**
- Go to [Reddit App Preferences](https://www.reddit.com/prefs/apps)
- 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**
```bash
cp .env.example .env
# Edit .env with your Reddit API credentials
```
5. **Build and test**
```bash
npm run build
npm run dev
```
## 🔧 Configuration
### Environment Variables
Create a `.env` file in the root directory:
```bash
# 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:
```json
{
"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:
```bash
# 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 [LICENSE](LICENSE) file for details.
## 🙏 Acknowledgments
- Inspired by the [Python Reddit MCP Server](https://github.com/Arindam200/reddit-mcp) by Arindam200
- Built following [Eugene Sh's MCP Server Tutorial](https://medium.com/@eugenesh4work/how-to-build-an-mcp-server-fast-a-step-by-step-tutorial-e09faa5f7e3b)
- 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](https://github.com/yourusername/reddit-mcp-server/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!*