Provides comprehensive Reddit integration with OAuth 2.1 authentication, enabling content discovery through search and subreddit browsing, user interaction management including notifications and messages, post and comment retrieval, and AI-assisted content analysis and generation.
systemprompt-mcp-server
Sponsored by systemprompt.io
This MCP server implementation is sponsored by — creators of the world's first native mobile MCP client for iOS and Android — and provided completely free and open source to the community.
If you find this project useful, we'd appreciate:
⭐ A star on this repository
👍 A like/follow on our social channels
🔗 Sharing with your network
Your support helps us continue creating valuable open source tools for the AI community!
🚀 Learn More: For an interactive walkthrough of this implementation with live SDK testing, visit systemprompt.io/mcp-server
A production-ready Model Context Protocol (MCP) server that demonstrates the complete MCP specification including OAuth 2.1, sampling, elicitation, structured data validation, and real-time notifications.
This implementation uses Reddit as a real-world example to demonstrate OAuth 2.1 flow and advanced MCP features, but the architecture is designed to be easily adapted for any API that requires OAuth authentication.
This server works with any MCP-compliant client that supports advanced features like sampling and notifications.
🔍 MCP Inspector Compatible
This server is fully compatible with the MCP Inspector, providing perfect support for:
✅ OAuth 2.1 Authentication - Complete flow with PKCE
✅ Tools - All Reddit interaction capabilities
✅ Prompts - Dynamic content generation prompts
✅ Sampling - AI-assisted content with human approval
✅ Notifications - Real-time progress updates
Test it yourself: npm run inspector
🌟 Why This Implementation Matters
OAuth 2.1 Demonstration with Reddit
This implementation uses Reddit's API as a real-world example to demonstrate how to build a complete OAuth 2.1 flow in an MCP server. Reddit was chosen because:
It requires OAuth authentication for most operations
It provides a rich API for demonstrating various MCP features
It's a well-documented, publicly accessible API
It showcases real-world authentication challenges and solutions
Note: While this server uses Reddit, the OAuth implementation and architecture patterns are designed to be easily adapted for any OAuth-based API (GitHub, Google, Slack, etc.).
Key Features Demonstrated
This repository serves as the gold standard for MCP server implementations, showcasing:
Complete MCP Spec Coverage: Every feature from OAuth to sampling is implemented
Production Architecture: Multi-user sessions, security, and scalability built-in
Developer Experience: Clean code structure perfect for learning or forking
Real-World OAuth Integration: Full OAuth 2.1 flow with PKCE, JWT tokens, and session management
AI-Native Design: Deep integration with LLMs for content generation and analysis
📚 Table of Contents
✨ Features
Core MCP Implementation
🔐 OAuth 2.1 Flow: Complete 8-step implementation with PKCE and JWT
🛠️ Tool System: Comprehensive tools for Reddit interaction
📚 Resources & Prompts: Dynamic prompt generation and resource management
🤖 Sampling: AI-assisted content generation with human oversight
💬 Elicitation: Dynamic user input gathering during tool execution
✅ Structured Data: JSON Schema validation for all inputs/outputs
📡 Notifications: Real-time progress updates and status notifications
🔄 Session Management: Multi-user support with automatic cleanup
Reddit Integration Features
Content Discovery: Search and analyze Reddit content
User Interactions: View messages, notifications, and manage account
Subreddit Information: Retrieve subreddit details and posts
Comment Threads: Navigate and analyze Reddit discussions
Developer Features
TypeScript: Full type safety with comprehensive interfaces
Modular Architecture: Clean separation of concerns
Error Handling: Robust error management with custom error types
Docker Support: Ready for containerized deployment
Testing: Example test implementations included
Documentation: Extensive inline documentation and examples
🚀 Quick Start
🐳 Simplest Installation (Docker with npx)
Run the server instantly with Docker - no installation required:
Step 1: Create Reddit App & Initial Config
Create a Reddit app at reddit.com/prefs/apps
Choose "script" type
Set redirect URI:
http://localhost:3000/oauth/reddit/callback
Create initial
.env
file:
Step 2: Run the Server
Step 3: Complete OAuth Authentication
In your MCP client, connect to
http://localhost:3000
The OAuth flow will start automatically
Authorize the app in your browser
Copy the returned OAuth token
Step 4: Update Environment with Token
Now you can use all Reddit tools with your authenticated session!
Installation
Configuration
Create Reddit App: reddit.com/prefs/apps
Choose "script" type
Set redirect URI:
http://localhost:3000/oauth/reddit/callback
Set Environment Variables:
Create a .env
file in the project root:
Note: Environment variables are required for both local development and Docker deployment.
Running the Server
🏗️ Architecture
This implementation follows clean architecture principles with clear separation between layers:
Key Components
src/server.ts
: Main HTTP server setup and Express configurationsrc/server/
: Core server infrastructure (MCP, OAuth, auth management)src/handlers/
: Request handlers for tools, prompts, resources, and samplingsrc/services/
: Business logic and Reddit API integrationsrc/constants/
: Tool definitions, server configuration, and schemassrc/types/
: TypeScript type definitions and interfaces
🔐 OAuth Implementation
This server implements the complete MCP OAuth 2.1 specification:
OAuth Flow Steps
Initial 401 Response (src/server/oauth.ts)
WWW-Authenticate: Bearer realm="MCP Reddit Server"Resource Metadata (src/server/oauth.ts)
{ "authorization_server": "http://localhost:3000/.well-known/oauth" }Authorization Server Metadata (src/server/oauth.ts)
Token endpoint configuration
PKCE support declaration
Grant types supported
Authorization Request (src/server/oauth.ts)
PKCE code challenge
State parameter for CSRF protection
Reddit OAuth redirect handling
Reddit OAuth Callback (src/server/oauth.ts)
Reddit authorization handling
Secure state validation
Token Exchange (src/server/oauth.ts)
PKCE verification
JWT token generation
Reddit credentials embedding
Authenticated Requests (src/server/middleware.ts)
JWT validation
Session management
Request context injection
Security Features
PKCE Implementation: Prevents authorization code interception
JWT Tokens: Secure credential storage and transmission
Session Isolation: Each user has isolated Reddit credentials
Automatic Cleanup: Sessions expire after inactivity
🛠️ Tool Reference
Content Discovery Tools
search_reddit
Search across Reddit with filters (src/handlers/tools/search-reddit.ts)
get_post
Fetch a specific post with comments (src/handlers/tools/get-post.ts)
get_channel
Get subreddit posts (src/handlers/tools/get-channel.ts)
User Interaction Tools
get_notifications
Fetch user notifications and messages (src/handlers/tools/get-notifications.ts)
get_comment
Retrieve a specific comment (src/handlers/tools/get-comment.ts)
Example and Development Tools
elicitation_example
Demonstrates user input gathering (src/handlers/tools/elicitation-example.ts)
sampling_example
Demonstrates AI-assisted content generation (src/handlers/tools/sampling-example.ts)
structured_data_example
Demonstrates structured data handling (src/handlers/tools/structured-data-example.ts)
validation_example
Demonstrates input validation (src/handlers/tools/validation-example.ts)
mcp_logging
Request server to log messages (src/handlers/tools/logging.ts)
🎯 Advanced Features
Sampling (AI-Assisted Content Generation)
The sampling implementation (src/handlers/sampling.ts) follows the complete MCP specification:
Elicitation (Dynamic Input Gathering)
Example implementation (src/handlers/tools/elicitation-example.ts):
Progress Notifications
Real-time updates during operations (src/handlers/notifications.ts):
Structured Data Validation
All inputs use Zod schema validation (src/handlers/tool-handlers.ts):
🎨 Using as a Template
This codebase is designed to be forked and adapted for other MCP implementations:
Step 1: Fork and Clone
Step 2: Replace Service Layer
Replace Reddit-specific services in src/services/
with your API:
Step 3: Define New Tools
Create tools in src/handlers/tools/
:
Step 4: Update Configuration
Modify src/constants/server/server-config.ts
:
💻 Development
Prerequisites
Node.js 18+
npm or yarn
Reddit account and app credentials
Development Commands
Testing
Testing with MCP Inspector
The server is fully compatible with the MCP Inspector, which provides a powerful interface for testing all MCP features:
This command will:
Build the TypeScript project
Open the MCP Inspector documentation in your browser
Launch the inspector connected to your local server
Full Feature Compatibility
The Reddit MCP server works perfectly with the MCP Inspector for:
🔐 OAuth Authentication: Complete OAuth 2.1 flow with PKCE support
🛠️ Tools: All Reddit interaction tools (search, get posts, notifications, etc.)
📚 Prompts: Dynamic prompt generation for content creation
🤖 Sampling: AI-assisted content generation with human-in-the-loop approval
📡 Notifications: Real-time progress updates during operations
✅ Structured Data: Full JSON Schema validation for inputs/outputs
The inspector provides:
Interactive tool testing with parameter validation
OAuth flow visualization and debugging
Sampling request/response inspection
Real-time notification monitoring
Session management visibility
Setting Up for Testing
Important: To run tests that interact with Reddit, you need to complete the OAuth flow first:
Start the server and open MCP Inspector:
# Build and start the server npm run build node build/index.js # In another terminal, open the MCP Inspector npx @modelcontextprotocol/inspector build/index.jsComplete OAuth Authentication:
The Inspector will prompt you to authenticate
Follow the OAuth flow to authorize with Reddit
After successful authentication, the server stores tokens
Save OAuth Tokens for Testing:
Once authenticated via Inspector, copy the generated tokens
Add them to your
.env
file for persistent testing:
# Add these to your .env after completing OAuth REDDIT_ACCESS_TOKEN=your_access_token REDDIT_REFRESH_TOKEN=your_refresh_token
Running Tests
Testing with Docker
Manual Testing
Docker Development
Quick Start with Docker
Manual Docker Commands
Environment Variables for Docker
Create a .env
file in the project root with the following variables:
Important: The docker:build-and-run
command requires these environment variables to be set either in a .env
file or exported in your shell. Without proper Reddit credentials, the OAuth flow will not work.
📁 Code Structure
Key Files
src/index.ts: Application entry point
src/server.ts: HTTP server setup and Express configuration
src/server/mcp.ts: MCP protocol implementation with session management
src/server/oauth.ts: Complete OAuth 2.1 flow
src/handlers/tool-handlers.ts: Tool execution with Zod validation
src/handlers/sampling.ts: AI sampling implementation
src/services/reddit/reddit-service.ts: Reddit API integration
🤝 Contributing
We welcome contributions! Please see our Contributing Guide for details.
Development Process
Fork the repository
Create a feature branch
Make your changes with tests
Submit a pull request
Code Style
Use TypeScript for all code
Follow the existing patterns
Add JSDoc comments for public APIs
Include tests for new features
🔗 Related Projects
Interactive Implementation Guide: Live testing and tutorial
MCP Specification: Official MCP documentation
systemprompt.io Documentation: Platform documentation
📄 License
This project is licensed under the MIT License - see the LICENSE file for details.
🙏 Acknowledgments
Anthropic for the MCP specification
Reddit for their comprehensive API
The MCP community for feedback and contributions
Built with ❤️ by the systemprompt.io team
This server cannot be installed
remote-capable server
The server can be hosted and run remotely because it primarily relies on remote services or has no dependency on the local environment.
Enables interaction with Reddit through OAuth 2.1 authentication, providing tools for searching content, managing notifications, analyzing posts and comments, and demonstrating advanced MCP features like sampling and real-time notifications.