mcp-auth-proxy

MCP Auth Proxy

If this project saves you time, please give it a star — it really helps visibility.

Quickstart

Domain binding & 80/443 must be accessible from outside.

Binary

Download binary from release page.

If you use stdio transport

./mcp-auth-proxy \
  --external-url https://{your-domain} \
  --tls-accept-tos \
  --password changeme \
  -- npx -y @modelcontextprotocol/server-filesystem /

If you use sse/http transport

./mcp-auth-proxy \
  --external-url https://{your-domain} \
  --tls-accept-tos \
  --password changeme \
  http://localhost:8080

This will automatically obtain and manage Let's Encrypt TLS certificates for your domain.

{
  "mcpServers": {
    "mcp": {
      "type": "http",
      "url": "https://{your-domain}/mcp"
    }
  }
}

Docker

If you use stdio transport

docker run --rm -p 80:80 -p 443:443 \
  -e EXTERNAL_URL=https://{your-domain} \
  -e TLS_ACCEPT_TOS=1 \
  -e PASSWORD=changeme \
  -v ./data:/data \
  ghcr.io/sigbit/mcp-auth-proxy:latest \
  -- npx -y @modelcontextprotocol/server-filesystem /

If you use sse/http transport

docker run --rm --net=host \
  -e EXTERNAL_URL=https://{your-domain} \
  -e TLS_ACCEPT_TOS=1 \
  -e PASSWORD=changeme \
  -v ./data:/data \
  ghcr.io/sigbit/mcp-auth-proxy:latest \
  http://localhost:8080

This will automatically obtain and manage Let's Encrypt TLS certificates for your domain.

{
  "mcpServers": {
    "mcp": {
      "type": "http",
      "url": "https://{your-domain}/mcp"
    }
  }
}

Overview

MCP Auth Proxy is a secure OAuth 2.1 authentication proxy for Model Context Protocol (MCP) servers. MCP servers are expected to support not only standard OAuth 2.1 flows but also Dynamic Client support (e.g., dynamic client registration) and authentication-related .well-known metadata. On top of that, different MCP clients handle tokens differently, which makes implementation tricky.

MCP Auth Proxy sits in front of your MCP services and enforces sign-in with OAuth providers (such as Google or GitHub) or password before users can access protected MCP resources.

Note

For a simpler approach to publish local MCP servers over OAuth, consider MCP Warp, which provides an OAuth Proxy + ngrok-like service. We highly recommend considering this option as well.

🔧 Configuration

Environment Variables

OAuth Provider Setup

Google OAuth Setup

1. Go to the Google Cloud Console
2. Create a new project or select an existing one
3. Enable the Google+ API
4. Create OAuth 2.0 credentials
5. Add authorized redirect URI: {EXTERNAL_URL}/.auth/google/callback

GitHub OAuth Setup

1. Go to the Register new GitHub App
2. Set Authorization callback URL: {EXTERNAL_URL}/.auth/github/callback

🚀 Usage

Method 1: Download Binary

Download the latest binary from releases and run with command line options:

./mcp-auth-proxy \
  --external-url "https://{your-domain}" \
  --tls-accept-tos \
  --password "changeme" \
  --google-client-id "your-google-client-id" \
  --google-client-secret "your-google-client-secret" \
  --google-allowed-users "user1@example.com,user2@example.com" \
  --github-client-id "your-github-client-id" \
  --github-client-secret "your-github-client-secret" \
  --github-allowed-users "username1,username2" \
  http://localhost:8080

Method 2: Docker

docker run --rm --net=host \
  -e EXTERNAL_URL=https://{your-domain} \
  -e TLS_ACCEPT_TOS=1 \
  -e PASSWORD=changeme \
  -e GOOGLE_CLIENT_ID="your-google-client-id" \
  -e GOOGLE_CLIENT_SECRET="your-google-client-secret" \
  -e GOOGLE_ALLOWED_USERS="user1@example.com,user2@example.com" \
  -e GITHUB_CLIENT_ID="your-github-client-id" \
  -e GITHUB_CLIENT_SECRET="your-github-client-secret" \
  -e GITHUB_ALLOWED_USERS="username1,username2" \
  -v ./data:/data \
  ghcr.io/sigbit/mcp-auth-proxy:latest \
  http://localhost:8080

🤝 Contributing

For developer guidelines, contribution instructions, and commit message conventions, please see CONTRIBUTING.md.

AI Development Environment Setup

You can link CONTRIBUTING.md to your preferred AI development environment for better integration:

# For Claude Code
ln -s CONTRIBUTING.md CLAUDE.md

# For Gemini
ln -s CONTRIBUTING.md GEMINI.md

# For GitHub Copilot
mkdir -p .github
ln -s CONTRIBUTING.md .github/copilot-instructions.md

This allows your AI assistant to access the contribution guidelines regardless of which development environment you prefer to use.