MCP Connector is a CLI tool and proxy server for the Model Context Protocol (MCP), providing secure, streamable HTTP transport with OAuth authentication support.

• 🔒 OAuth2 PKCE authentication flow
• 🔗 Streamable HTTP proxy for MCP clients
• 🛠️ CLI for managing tokens, logs, and server connections
• 📦 Token storage and management in ~/.mcp-connector
• 📝 Easy integration with the MCP SDK
• 🖥️ Native OS dialogs for authentication (macOS, Windows, Linux)
• 📋 Automatic browser launch or copy OAuth URL to clipboard
• 🧹 Cleanup logic for tokens, logs, and server state
• 🏷️ Static headers support: Add static headers (including Authorization) to MCP server requests. If an Authorization header is present, it will be used as static authentication and OAuth 2.1 will not be triggered.

npm install -g mcp-connector

Or use with npx:

npx mcp-connector [options]

mcp-connector [options]

# CLI usage documentation
npx mcp-connector --help
npx mcp-connector -h

# Connect to a single MCP server
npx mcp-connector --inline-config mcp-connector-server http://localhost:3000

# Connect using a config file
npx mcp-connector --config ./my-config.json --server-name mcp-connector-server

# Connect to a server with headers
npx mcp-connector --inline-config mcp-connector-server http://localhost:3000 --headers '{"header1":"value1","header2":"value2"}'

# List all URL hash mappings
npx mcp-connector --url-map

# List all stored tokens
npx mcp-connector --list-tokens

# Clean expired tokens
npx mcp-connector --clean-tokens

# Remove all MCP Connector data
npx mcp-connector --clean-all

# Enable debug mode
npx mcp-connector --debug [--options]

You can specify servers directly:

npx mcp-connector --inline-config mcp-connector-server http://localhost:3000

Example my-config.json:

{
  "server-name": { 
    "name": "local", # If not provided, the object key will be used as the server name
    "url": "http://localhost:3000",
    "port": 8080 # OAuth callback port (optional)
  }
}

• Tokens and logs are stored in ~/.mcp-connector/{server_hash}/
• Each token file is named with the SHA256 hash of the URL and mapped in url-hash-map.json

• When authentication is required, MCP Connector will:
  • Show a native OS dialog/notification (macOS, Windows, Linux) to guide you through OAuth.
  • Open the browser automatically or copy the OAuth URL to your clipboard.
  • Wait for authentication to complete (timeout: 5 minutes).
  • Store tokens securely in ~/.mcp-connector/{server_hash}/.
  • Local Authentication Server will close 5 seconds after successful OAuth.
  • MCP Connector currently implements an automatic retry mechanism:
    • If a 401 Unauthorized error is encountered, the connector will retry the request up to 3 times before failing.

On process exit (SIGINT, SIGTERM), MCP Connector will:

• 🛑 Close all proxy transports.
• 🧹 Clean up pending initialization errors.
• 🗑️ Clear global state stores.
• 🧽 Clean expired tokens.
• 📴 Stop the OAuth proxy server.
• 🗂️ Clear server configs.

npm install
npm run build
npm run build:watch # Start the TypeScript watcher

• Fetch failed:

  • Ensure the MCP server URL is correct and reachable.
  • Check for SSL certificate issues.
  • Make sure the server is running and listening on the correct port.

• Dialog/Clipboard issues:

  • Make sure required OS utilities (osascript, powershell, zenity, pbcopy, clip, xclip, xsel) are available.

MIT

slokendra2102@gmail.com

Pull requests and issues are welcome!