FastMCP OAuth

OAuth 2.1 + PKCE authentication for FastMCP servers with support for Google, Microsoft, and GitHub.

✨ Features

• 🔐 OAuth 2.1 + PKCE - Standards-compliant authentication
• 🏢 Multiple Providers - Google, Microsoft Entra ID, GitHub
• 🛡️ Scope-based Authorization - Granular permission control
• 📱 MCP Tools - Authenticated AI tool access
• 🚀 Production Ready - Comprehensive error handling & security

🚀 Quick Start

Installation

# From PyPI (when published)
pip install fastmcp-oauth

# From Git
pip install git+https://github.com/peterlarnholt/fastmcp-oauth.git

# With Poetry
poetry add git+https://github.com/peterlarnholt/fastmcp-oauth.git

Usage

from fastmcp import FastMCP
from fastmcp_oauth import MicrosoftOAuth, require_auth

# Create server
mcp = FastMCP("My Server")

# Add Microsoft OAuth (3 lines!)
oauth = MicrosoftOAuth.from_env()
app = oauth.install(mcp)

# Protected tool
@mcp.tool()
@require_auth
async def get_user_info(ctx) -> str:
    user = ctx.auth.user
    return f"Hello {user.name}! Email: {user.email}"

Environment Variables

SECRET_KEY=your-secret-key-32-chars-minimum
MICROSOFT_CLIENT_ID=your-microsoft-client-id
MICROSOFT_CLIENT_SECRET=your-microsoft-client-secret
MICROSOFT_TENANT=common  # or your tenant ID

🔧 Providers

Microsoft Entra ID

from fastmcp_oauth import MicrosoftOAuth

oauth = MicrosoftOAuth.from_env()

Google OAuth

from fastmcp_oauth import GoogleOAuth

oauth = GoogleOAuth.from_env()

GitHub OAuth

from fastmcp_oauth import GitHubOAuth

oauth = GitHubOAuth.from_env()

Multi-Provider (Auto-detected)

from fastmcp_oauth import OAuthProvider

# Detects all configured providers
oauth = OAuthProvider.from_env()

🛡️ Authorization

Basic Authentication

@mcp.tool()
@require_auth
async def protected_tool(ctx) -> str:
    return f"Hello {ctx.auth.user.name}!"

Scope-based Authorization

@mcp.tool()
@require_scope("admin")
async def admin_tool(ctx) -> str:
    return "Admin operation"

User-based Authorization

@mcp.tool()
@require_user(domain="company.com")
async def company_tool(ctx) -> str:
    return "Company-only tool"

@mcp.tool()
@require_user(provider="microsoft")
async def microsoft_only(ctx) -> str:
    return "Microsoft users only"

📚 Documentation

• Setup Guides: Provider-specific setup instructions
• API Reference: Complete API documentation
• Examples: Working examples for each provider
• Security: Best practices and security considerations

🔗 Provider Setup

Microsoft Entra ID

1. Go to Azure Portal
2. Navigate to Azure Active Directory → App registrations
3. Create new registration
4. Add redirect URI: http://localhost:8000/oauth/callback
5. Generate client secret
6. Configure API permissions: User.Read, openid, profile, email

Google OAuth

1. Go to Google Cloud Console
2. Create OAuth 2.0 credentials
3. Add redirect URI: http://localhost:8000/oauth/callback
4. Configure OAuth consent screen

GitHub OAuth

1. Go to GitHub Settings → Developer settings → OAuth Apps
2. Create new OAuth app
3. Set Authorization callback URL: http://localhost:8000/oauth/callback

🧪 Testing

# Test with MCP Inspector
npx @modelcontextprotocol/inspector http://localhost:8000/sse

📄 License

MIT License - see LICENSE file for details.

🤝 Contributing

Contributions welcome! Please read our contributing guidelines.

🔧 Development

git clone https://github.com/peterlarnholt/fastmcp-oauth.git
cd fastmcp-oauth
pip install -e ".[dev]"
pytest