decodo-back-office-mcp

Decodo Back Office MCP Server

A Model Context Protocol (MCP) server that provides seamless integration with Decodo's proxy management API, enabling AI agents to manage proxy infrastructure, sub-users, traffic monitoring, and endpoint configuration.

Features

🔧 Sub-User Management

• Create, read, update, and delete sub-users
• Track individual sub-user traffic and usage
• Manage sub-user permissions and quotas

🌐 Proxy Endpoint Management

• Retrieve available proxy endpoints
• Generate custom endpoint configurations
• Monitor endpoint health and analyze targets

🛡️ IP Whitelist Management

• Add/remove IP addresses from whitelist
• Bulk whitelist operations
• Manage IP configurations with descriptions

📊 Traffic & Usage Analytics

• Real-time traffic monitoring
• Historical usage data retrieval
• Target analysis and reporting
• Subscription and quota monitoring

Installation

Via npx (Easiest - No Installation Required)

npx -y decodo-back-office-mcp

Via NPM Global Install

npm install -g decodo-back-office-mcp
decodo-mcp

From Source

git clone https://github.com/andrewlwn77/decodo-back-office-mcp.git
cd decodo-back-office-mcp
npm install
npm run build
npm start

Quick Start

1. Get Your Decodo API Key

• Log into your Decodo Dashboard
• Navigate to "API Keys" section
• Generate a new API key

2. Configure Environment

Create a .env file in your project directory:

DECODO_API_KEY=your_api_key_here
DECODO_BASE_URL=https://api.decodo.com/v2
LOG_LEVEL=info

3. MCP Configuration

For Claude Desktop

Option A: Using npx (Recommended - No Installation Required) Add to your claude_desktop_config.json:

{
  "mcpServers": {
    "decodo-back-office": {
      "command": "npx",
      "args": ["-y", "decodo-back-office-mcp"],
      "env": {
        "DECODO_API_KEY": "your_api_key_here"
      }
    }
  }
}

Option B: Using Global Install

{
  "mcpServers": {
    "decodo-back-office": {
      "command": "decodo-mcp",
      "env": {
        "DECODO_API_KEY": "your_api_key_here"
      }
    }
  }
}

Option C: From Source

{
  "mcpServers": {
    "decodo-back-office": {
      "command": "node",
      "args": ["/path/to/decodo-back-office-mcp/dist/index.js"],
      "env": {
        "DECODO_API_KEY": "your_api_key_here"
      }
    }
  }
}

For Continue.dev

Using npx (Recommended): Add to your config.json:

{
  "experimental": {
    "modelContextProtocol": true
  },
  "mcpServers": {
    "decodo-back-office": {
      "transport": {
        "type": "stdio"
      },
      "command": "npx",
      "args": ["-y", "decodo-back-office-mcp"],
      "env": {
        "DECODO_API_KEY": "your_api_key_here"
      }
    }
  }
}

For Cline (VS Code)

Using npx (Recommended): Add to your MCP settings:

{
  "mcpServers": {
    "decodo-back-office": {
      "command": "npx",
      "args": ["-y", "decodo-back-office-mcp"],
      "env": {
        "DECODO_API_KEY": "your_api_key_here"
      }
    }
  }
}

Manual Server Start

# Using npx (easiest)
npx -y decodo-back-office-mcp

# Using global install
npm install -g decodo-back-office-mcp
decodo-mcp

# Development (from source)
npm run dev

# Production (from source)
npm run build
npm start

Configuration

Environment Variables

Variable	Required	Default	Description
DECODO_API_KEY	✅ Yes	-	Your Decodo API key
DECODO_BASE_URL	No	https://api.decodo.com/v2	Decodo API base URL
LOG_LEVEL	No	info	Logging level (error, warn, info, debug)
MCP_SERVER_NAME	No	decodo-back-office-mcp	Server identification
MCP_SERVER_VERSION	No	1.0.0	Server version

Finding Configuration Paths

Claude Desktop Config Location

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows: %APPDATA%\Claude\claude_desktop_config.json
• Linux: ~/.config/Claude/claude_desktop_config.json

Continue.dev Config Location

• All Platforms: ~/.continue/config.json

Available Tools

The server provides 14 MCP tools for complete Decodo proxy management:

🔧 Sub-User Management (6 tools)

Tool	Description	Parameters
decodo_create_sub_user	Create a new sub-user	username, password?, email?, traffic_limit?
decodo_get_sub_users	List all sub-users	None
decodo_get_sub_user	Get specific sub-user details	id
decodo_update_sub_user	Update existing sub-user	id, username?, password?, email?, traffic_limit?
decodo_delete_sub_user	Delete a sub-user	id
decodo_get_sub_user_traffic	Get sub-user traffic statistics	id, start_date?, end_date?

🌐 Proxy Management (3 tools)

Tool	Description	Parameters
decodo_get_endpoints	Retrieve proxy endpoints	None
decodo_generate_endpoint	Generate custom endpoints	protocol?, format?, custom_params?
decodo_get_target_info	Analyze target URLs	url

🛡️ IP Whitelist (3 tools)

Tool	Description	Parameters
decodo_get_whitelist	List whitelisted IPs	None
decodo_add_whitelist_ip	Add IP to whitelist	ip, description?
decodo_remove_whitelist_ip	Remove IP from whitelist	ip

📊 Analytics (2 tools)

Tool	Description	Parameters
decodo_get_traffic	Get traffic statistics	start_date?, end_date?, sub_user_id?
decodo_get_subscriptions	View subscription information	None

Example Usage

Using with Claude Desktop

Once configured, you can ask Claude:

"Can you show me all my Decodo sub-users and their traffic usage?"

"Please create a new sub-user called 'test-user' with a 1GB traffic limit"

"Add IP address 192.168.1.100 to my whitelist for my home office"

"Generate a custom HTTPS endpoint for JSON responses"

Using with API

// The server will automatically handle tool calls through MCP protocol
// Your AI client will have access to all 14 Decodo management tools

Troubleshooting

Common Issues

Server won't start:

• Check that DECODO_API_KEY is set in your environment
• Verify Node.js version is 18+ (node --version)
• Run npm run build to ensure compilation

API errors:

• Verify your Decodo API key is valid
• Check that your Decodo account has necessary permissions
• Ensure DECODO_BASE_URL is set to https://api.decodo.com/v2

MCP client can't connect:

• Ensure the server path in your MCP config is correct
• Check that the server process is running
• Verify environment variables are passed correctly

Debug Mode

Enable debug logging:

LOG_LEVEL=debug npm start

Security & Best Practices

• ✅ API keys are securely handled and never logged
• ✅ All requests include proper authentication headers
• ✅ Input validation using Zod schemas
• ✅ Comprehensive error handling with sanitized logs
• ✅ TypeScript for compile-time type safety
• ✅ .gitignore prevents credential leakage

Development

Building

npm run build

Testing

npm test
npm run test:coverage

Linting

npm run lint
npm run lint:fix

Type Checking

npm run typecheck

API Reference

For detailed Decodo API documentation, visit: Decodo API Documentation

License

MIT License - see LICENSE file for details.

Contributing

• Fork the repository
• Create a feature branch
• Make your changes
• Add tests for new functionality
• Ensure all tests pass
• Submit a pull request

Support

• MCP Server Issues: GitHub Issues
• Decodo API: Decodo Support
• MCP Protocol: MCP Documentation

Built with the BMAD Agent Team methodology for comprehensive multi-perspective development.