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

1. Log into your Decodo Dashboard
2. Navigate to "API Keys" section
3. 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

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Add tests for new functionality
5. Ensure all tests pass
6. 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.