MCP OAuth Framework

The "Rails for MCP OAuth" - Build OAuth-enabled MCP servers in minutes, not hours.

Transform 200+ lines of OAuth boilerplate into 20 lines of clean, production-ready code.

⚡ Quick Start (2 Minutes)

npm install @sg20/mcp-oauth-framework

Create a GitHub MCP Server:

import { BaseMCPServer } from '@sg20/mcp-oauth-framework/base';

class GitHubServer extends BaseMCPServer {
  constructor() {
    super({
      name: 'github-server',
      version: '1.0.0',
      providers: [{
        name: 'github',
        clientId: process.env.GITHUB_CLIENT_ID!,
        authorizationUrl: 'https://github.com/login/oauth/authorize',
        tokenUrl: 'https://github.com/login/oauth/access_token',
        scope: ['repo', 'user:email']
      }]
    });
  }

  async initialize() {
    this.addTool({
      name: 'list-repos',
      description: 'List user repositories',
      auth: { required: true, provider: 'github' },
      handler: async () => {
        const response = await this.makeAuthenticatedRequest(
          'github', 
          'https://api.github.com/user/repos'
        );
        return response.json();
      }
    });
  }
}

new GitHubServer().start();

That's it! You now have a fully functional OAuth-enabled MCP server with:

✅ Secure PKCE OAuth 2.0 flow
✅ Automatic token management
✅ Browser-based authentication
✅ Production-ready error handling

🎯 Why This Framework?

❌ Without Framework (The Hard Way)

// 200+ lines of OAuth boilerplate:
// - PKCE implementation
// - Token storage & encryption  
// - Browser flow management
// - Token refresh logic
// - Error handling
// - Security validation
// - MCP integration
// ... and much more

✅ With Framework (The Easy Way)

// 20 lines of clean code:
class MyServer extends BaseMCPServer {
  constructor() {
    super({ providers: [oauthProvider] });
  }
  async initialize() {
    this.addTool(/* your tool */);
  }
}

Result: 90% less code, 100% more reliability

🚀 Complete Example: GitHub MCP Server

See our complete GitHub server example that demonstrates:

15 GitHub API tools - repos, issues, PRs, files, search
Production-ready - full error handling, validation, logging
2-minute setup - simple .env configuration
Real OAuth flow - works with Claude Desktop out of the box

Live Example Usage

User: "List my GitHub repositories"

What happens:

🌐 Browser opens to GitHub OAuth page
✅ User clicks "Authorize"
🔄 Tokens stored securely locally
📋 Repository list appears in Claude
🚀 Next time: instant results (no browser needed)

🏗️ Framework Architecture

Core Modules

@sg20/mcp-oauth-framework/
├── base              # MCP server foundation
│   ├── BaseMCPServer # Abstract base class
│   └── ToolRegistry  # Tool management with auth
├── auth              # OAuth implementation  
│   ├── AuthManager   # Authentication orchestrator
│   ├── OAuthFlow     # PKCE browser flow
│   └── TokenStore    # Secure token storage
└── shared            # Common utilities
    ├── types         # TypeScript interfaces
    └── utils         # OAuth helpers & validation

Security Features

🔐 PKCE Flow - Proof Key for Code Exchange prevents code interception
🔒 Encrypted Storage - Tokens encrypted with machine-specific keys
🔄 Auto Refresh - Expired tokens refreshed automatically
✅ Scope Validation - Tools validate required OAuth permissions
🛡️ Secure Defaults - Minimal permissions, safe storage locations

📚 Framework API

BaseMCPServer

The foundation for all OAuth-enabled MCP servers:

class MyServer extends BaseMCPServer {
  constructor(options: BaseMCPServerOptions) {
    super(options);
  }

  // Required: Implement your server initialization
  async initialize(): Promise<void> {
    this.addTool({
      name: 'my-tool',
      description: 'My awesome tool',
      auth: { required: true, provider: 'github', scopes: ['repo'] },
      handler: async (params, context) => {
        // context.auth contains authenticated user info
        return await this.makeAuthenticatedRequest('github', '/api/endpoint');
      }
    });
  }

  // Required: Cleanup on shutdown
  async cleanup(): Promise<void> {
    // Your cleanup logic
  }
}

Available Methods

// Tool registration
protected addTool(definition: ToolDefinition): void

// Authenticated API requests
protected makeAuthenticatedRequest(
  provider: string, 
  url: string, 
  options?: RequestInit,
  requiredScopes?: string[]
): Promise<Response>

// Manual authentication
protected requireAuth(provider: string, scopes?: string[]): Promise<AuthenticatedRequest>

// Logging
protected log(message: string, level?: 'info' | 'warn' | 'error'): void

OAuth Provider Configuration

interface OAuthProvider {
  name: string;                    // Unique identifier (e.g., 'github')
  clientId: string;               // OAuth client ID
  clientSecret?: string;          // OAuth client secret (optional with PKCE)
  authorizationUrl: string;       // Authorization endpoint
  tokenUrl: string;              // Token exchange endpoint  
  scope: string[];               // Required OAuth scopes
  additionalParams?: Record<string, string>; // Extra parameters
}

Tool Definition

interface ToolDefinition {
  name: string;                   // Tool name (kebab-case)
  description: string;           // Tool description for users
  auth?: {                       // Authentication requirements
    required: boolean;
    provider?: string;           // OAuth provider name
    scopes?: string[];          // Required scopes
    message?: string;           // Custom auth prompt
  };
  handler: (params: any, context: RequestContext) => Promise<any>;
}

🛠️ Supported OAuth Providers

Built-in Support

GitHub - Repositories, issues, pull requests, files
Google - Drive, Gmail, Calendar APIs
Microsoft - Office 365, OneDrive, Teams
Custom - Easy to add any OAuth 2.0 provider

Adding Custom Providers

const customProvider: OAuthProvider = {
  name: 'my-service',
  clientId: process.env.MY_SERVICE_CLIENT_ID!,
  authorizationUrl: 'https://myservice.com/oauth/authorize',
  tokenUrl: 'https://myservice.com/oauth/token',
  scope: ['read', 'write'],
  additionalParams: {
    audience: 'https://myservice.com/api'
  }
};

🎮 Usage with Claude Desktop

Simple Configuration

Add to your Claude Desktop config (~/Library/Application Support/Claude/claude_desktop_config.json):

{
  "mcpServers": {
    "my-server": {
      "command": "node",
      "args": ["/path/to/your/server/dist/index.js"]
    }
  }
}

That's it! The server automatically:

✅ Reads configuration from .env file
✅ Validates OAuth credentials
✅ Provides helpful error messages
✅ Handles authentication flow

Environment Configuration

Create .env in your server directory:

# Required
GITHUB_CLIENT_ID=your_github_client_id

# Optional but recommended  
GITHUB_CLIENT_SECRET=your_github_client_secret

# Optional: Enable debug logging
DEBUG=false

🏃‍♂️ Getting Started

1. Try the Example

The fastest way to understand the framework:

git clone https://github.com/swayamg20/mcp-framework.git
cd mcp-framework/examples/github-server

# Follow the 2-minute setup guide
cat SIMPLE-SETUP.md

2. Build Your Own Server

mkdir my-mcp-server && cd my-mcp-server
npm init -y
npm install @sg20/mcp-oauth-framework dotenv

# Create your server (see API examples above)
# Add to Claude Desktop config
# Start building amazing OAuth tools!

3. Join the Community

GitHub Issues - Bug reports and feature requests
Discussions - Share your servers and get help
Examples - Browse community-built servers
Contributing - Help improve the framework

🔧 Advanced Usage

Multi-Provider Servers

class MultiServiceServer extends BaseMCPServer {
  constructor() {
    super({
      name: 'multi-service-server',
      version: '1.0.0',
      providers: [
        githubProvider,
        googleProvider,
        slackProvider
      ]
    });
  }
}

Custom Tool Middleware

this.addTool({
  name: 'advanced-tool',
  description: 'Tool with custom logic',
  auth: { required: true, provider: 'github', scopes: ['repo'] },
  handler: async (params, context) => {
    // Access authenticated user info
    const { tokens, user } = context.auth!;
    
    // Custom validation
    if (!user.email?.endsWith('@company.com')) {
      throw new Error('Only company users allowed');
    }
    
    // Make multiple authenticated requests
    const [repos, issues] = await Promise.all([
      this.makeAuthenticatedRequest('github', '/user/repos'),
      this.makeAuthenticatedRequest('github', '/issues')
    ]);
    
    return { repos: await repos.json(), issues: await issues.json() };
  }
});

Error Handling

try {
  const result = await this.makeAuthenticatedRequest('github', '/user/repos');
  return result.json();
} catch (error) {
  if (error.code === 'AUTHENTICATION_REQUIRED') {
    // User needs to re-authenticate
    throw new Error('Please re-authenticate with GitHub');
  }
  if (error.code === 'INSUFFICIENT_SCOPE') {
    // User needs more permissions
    throw new Error('Additional GitHub permissions required');
  }
  // Handle other errors
  throw error;
}

🚀 Production Deployment

Environment Variables

# Required
GITHUB_CLIENT_ID=your_production_client_id

# Recommended for production
GITHUB_CLIENT_SECRET=your_production_client_secret

# Optional configuration
DEBUG=false
OAUTH_PORT=8080
OAUTH_HOST=localhost
OAUTH_CALLBACK_PATH=/oauth/callback

Security Best Practices

✅ Use HTTPS in production - Configure proper callback URLs
✅ Validate all inputs - Framework provides validation helpers
✅ Monitor token usage - Implement logging and monitoring
✅ Regular security updates - Keep dependencies updated
✅ Never commit secrets - Always use environment variables

Performance Tips

🚀 Token reuse - Framework automatically caches valid tokens
🚀 Concurrent requests - Use Promise.all() for parallel API calls
🚀 Scope optimization - Request only necessary permissions
🚀 Error recovery - Implement retry logic for transient failures

📖 Documentation

GitHub Server Example - Production-ready implementation
Simple Setup Guide - 2-minute setup
Usage Guide - Comprehensive tutorial

🤝 Contributing

We welcome contributions! Here's how to get started:

Fork the repository
Create a feature branch: git checkout -b feature/amazing-feature
Make your changes with tests and documentation
Submit a pull request

Development Setup

git clone https://github.com/swayamg20/mcp-framework.git
cd mcp-framework
npm install
npm run build
npm test

Adding New OAuth Providers

Add provider configuration to types
Implement user info normalization
Add example usage
Update documentation
Submit PR with tests

📊 Framework Stats

🏗️ Architecture: Modular, extensible, type-safe
🔒 Security: PKCE, encrypted storage, scope validation
📝 Code Reduction: 90% less OAuth boilerplate
⚡ Performance: Automatic token caching and refresh
🧪 Testing: Comprehensive test suite
📚 Documentation: Complete API reference and examples

📄 License

MIT License - see LICENSE file for details.

🆘 Support & Community

🐛 Bug Reports: GitHub Issues
💬 Discussions: GitHub Discussions
📚 Documentation: Complete guides and API reference included
💡 Feature Requests: Submit ideas via GitHub Issues

Ready to build OAuth-enabled MCP servers in minutes instead of hours?

🚀 Try the GitHub Example

Made with ❤️ for the MCP community. Empowering developers to build amazing AI integrations.

Name		Name	Last commit message	Last commit date
.github		.github
examples/github-server		examples/github-server
src		src
.gitignore		.gitignore
.npmignore		.npmignore
CLAUDE.md		CLAUDE.md
README.md		README.md
TODO.md		TODO.md
USAGE_GUIDE.md		USAGE_GUIDE.md
package.json		package.json
plan.md		plan.md
tsconfig.json		tsconfig.json

Latest commit

History

Folders and files

Repository files navigation