Box MCP Proxy Server

A proxy server that bridges STDIO-based MCP clients with Box's remote MCP server over HTTP. This proxy handles Box OAuth 2.0 authentication and forwards MCP messages between clients and the Box remote server.

Quick Setup

New users should run the interactive setup:

python setup.py

This will:

• Create virtual environment and install dependencies
• Guide you through entering Box API credentials securely
• Configure secure token storage (keychain, memory, or encrypted)
• Set appropriate file permissions
• Provide Claude Desktop configuration with correct Python path

Manual Setup

1. Create Virtual Environment and Install Dependencies

   python -m venv .venv
   source .venv/bin/activate  # On Windows: .venv\Scripts\activate
   pip install -r requirements.txt
   

2. Configure Credentials Either run python setup.py (recommended) or manually create .env:

   Required variables:

   • BOX_CLIENT_ID: Your Box application's client ID
   • BOX_CLIENT_SECRET: Your Box application's client secret (or stored in keychain via setup)
   • TOKEN_STORAGE_TYPE: Security option (see Security section)

3. Box Application Setup

   • Create a Box application at https://developer.box.com
   • Configure OAuth 2.0 with redirect URI: http://localhost:8080/callback
   • Ensure your application has the necessary scopes

Usage

As a Standalone Server

python main.py

With MCP Clients

Configure your MCP client to use this proxy as an STDIO server:

{
  "mcpServers": {
    "box-remote-mcp-proxy": {
      "command": "/path/to/box-remote-mcp-proxy/.venv/bin/python",
      "args": ["/path/to/box-remote-mcp-proxy/main.py"]
    }
  }
}

Authentication Flow

1. On first run, the proxy will open a browser for Box OAuth authorization
2. After successful authorization, tokens are saved locally
3. Tokens are automatically refreshed when expired
4. Re-authentication is triggered when refresh fails

Architecture

• STDIO Interface: Receives JSON-RPC messages from MCP clients
• OAuth Manager: Handles Box authentication and token management
• HTTP Client: Sends authenticated requests to Box MCP server
• Proxy Logic: Forwards messages between STDIO and HTTP transports

Security

The proxy supports multiple secure credential and token storage options:

• Keyring (default): Uses OS keychain for tokens and optionally client secrets (macOS Keychain, Windows Credential Manager)
• Memory: Stores tokens only in memory, requires re-auth on restart (most secure)
• Encrypted: Encrypts tokens with random keys stored in keychain
• Plaintext: Plain JSON file (development only)

Key security features:

• Client secrets can be stored in keychain (via setup script)
• Tokens use secure storage separate from credentials
• File permissions automatically set to 600 (owner read/write only)
• Credential format validation prevents typos

See SECURITY.md for detailed security configuration options.

Files

• main.py: Entry point and signal handling
• setup.py: Interactive setup script for new users
• config.py: Environment variable configuration
• auth/oauth.py: Box OAuth 2.0 implementation
• auth/secure_storage.py: OS keychain token storage
• auth/memory_storage.py: Memory-only token storage
• auth/encrypted_storage.py: Encrypted file token storage
• transport/http_client.py: Streamable HTTP client for Box MCP server
• proxy/server.py: Main proxy server logic
• stdio_reader.py: Async STDIO message reader
• logger.py: Logging configuration
• SECURITY.md: Security configuration guide