Freelance MCP Server - Installation and Usage Guide

A comprehensive freelance platform aggregator MCP server that helps users find gigs, generate proposals, negotiate rates, and optimize their freelance profiles using AI

📖 Documentation Quick Links

• QUICK_REFERENCE.md - Quick commands & tool reference

• VALIDATION_STATUS.md - Test results & production status

• DEBUG_REPORT.md - Bug fixes & debugging summary

• STRUCTURE.md - Project organization & file structure

• FINAL_SUMMARY.md - Complete debugging summary

Related MCP server: Upwork MCP Server

🚀 Quick Start for Claude Desktop Users

Want to use this with Claude Desktop right away? Follow these 3 steps:

1. Get a GROQ API Key (free): Visit console.groq.com, sign up, and create an API key

2. Add to Claude Desktop config - Edit your claude_desktop_config.json:

   • Windows: %APPDATA%\Claude\claude_desktop_config.json

   • Mac: ~/Library/Application Support/Claude/claude_desktop_config.json

   Add this to the mcpServers section (replace paths and keys with yours):

   {
     "mcpServers": {
       "freelance": {
         "command": "uv",
         "args": [
           "run",
           "--with", "mcp",
           "--with", "python-dotenv",
           "--with", "langchain-groq",
           "--with", "pydantic",
           "C:\\path\\to\\your\\freelance_server.py",
           "stdio"
         ],
         "env": {
           "GROQ_API_KEY": "gsk_your_key_here",
           "OWNER_COUNTRY_CODE": "1",
           "OWNER_PHONE_NUMBER": "5551234567"
         }
       }
     }
   }

3. Restart Claude Desktop and start using commands like:

   • "Search for Python gigs under $1000"

   • "Show me freelance market trends"

   • "Generate a proposal for gig upwork_001"

Need more detailed instructions? See Integration with Claude Desktop below.

File Structure

mcp-server-1/
├── freelance_server.py          # Main MCP server (run this!)
├── requirements.txt             # Dependencies
├── .env.example                 # Environment template
├── README.md                    # This file
├── STRUCTURE.md                 # Detailed structure guide
│
├── core/                        # Core modules
├── database/                    # Database layer
├── mcp_extensions/              # MCP protocol extensions
├── utils/                       # Utilities
│
├── tests/                       # Test suite
├── examples/                    # Example code
├── docs/                        # Documentation
│
└── .github/                     # GitHub templates & workflows

See STRUCTURE.md for complete directory documentation.

Quick Start

1. Prerequisites

• Python 3.8 or higher

• pip package manager

• Git (optional, for cloning repositories)

2. Installation

# Install required dependencies
uv pip install -r requirements.txt

# Or install individual packages
uv pip install mcp langchain-groq pydantic python-dotenv

3. Environment Setup

Create a .env file in your project directory with your API keys:

# Windows
echo GROQ_API_KEY=your_actual_key_here > .env
echo OWNER_COUNTRY_CODE=1 >> .env
echo OWNER_PHONE_NUMBER=5551234567 >> .env

# Linux/Mac
cat > .env << EOF
GROQ_API_KEY=your_actual_key_here
OWNER_COUNTRY_CODE=1
OWNER_PHONE_NUMBER=5551234567
EOF

Required Environment Variables:

• GROQ_API_KEY - Your Groq API key (get from https://console.groq.com/)

• OWNER_COUNTRY_CODE - Country code without + (e.g., 1 for US, 44 for UK)

• OWNER_PHONE_NUMBER - Phone number without country code or special characters

• MCP_AUTH_TOKEN - (Optional) Authentication token for advanced setups

4. Get GROQ API Key

1. Visit Groq Console

2. Sign up or log in

3. Create a new API key

4. Copy it to your .env file

5. Run the Server

Option A: Test Server Directly (for development)

# Test server in stdio mode
python freelance_server.py stdio

# Or with uv and dependencies
uv run --with mcp --with python-dotenv --with langchain-groq --with pydantic freelance_server.py stdio

Option B: Use with Claude Desktop (recommended)

See the Integration with Claude Desktop section below for full setup instructions.

6. Run the Client

# Check environment setup
python freelance_client.py --check-env

# Run automated demo
python freelance_client.py --mode demo

# Run interactive mode
python freelance_client.py --mode interactive

File Structure

your-project/
├── freelance_server.py     # MCP Server (main server file)
├── freelance_client.py     # MCP Client (optional - for testing)
├── freelance_client2.py    # MCP Client (alternative implementation)
├── main.py                 # Demo file
├── requirements.txt        # Dependencies
├── .env                    # Environment variables (create this)
├── README.md               # This guide
└── setup.py                # Setup configuration

Usage Examples

Automated Demo Mode (Recommended)

python freelance_client.py --mode demo

This will run through all features automatically:

• 🔍 Gig searching and filtering

• 👤 User profile creation and analysis

• 📝 AI-powered proposal generation

• 💰 Rate negotiation strategies

• 🔍 Code review with quality metrics

• 🐛 Automated code debugging and fixing

• ⚡ Profile optimization recommendations

• 📚 Resource access and market insights

Interactive Mode

python freelance_client.py --mode interactive

Available commands in interactive mode:

• search - Search for matching gigs

• profile - Create user profile

• analyze - Analyze profile fit for gigs

• proposal - Generate AI proposals

• negotiate - Get rate negotiation help

• review - Review code quality

• debug - Debug and fix code issues

• optimize - Get profile optimization tips

• resources - Access market data

• demo - Run full automated demo

• quit - Exit

Key Features Demonstrated

1. Gig Search and Matching

# Example: Search for React gigs under $1000
result = client.search_gigs(
    skills=["JavaScript", "React", "TypeScript"],
    max_budget=1000,
    project_type="fixed_price"
)

2. AI-Powered Proposal Generation

# Generate personalized proposals using ChatGroq LLM
proposal = client.generate_proposal(
    gig_id="upwork_001",
    user_profile=profile_data,
    tone="professional"
)

3. Code Review Tool

# Analyze code quality and get suggestions
review = client.code_review(
    file_path="./src/component.js",
    review_type="general"
)

4. Code Debug Tool

# Automatically fix common code issues
debug_result = client.code_debug(
    file_path="./buggy_code.js",
    issue_description="Replace var with let/const",
    fix_type="auto"
)

5. Rate Negotiation

# Get AI-powered negotiation strategies
negotiation = client.negotiate_rate(
    current_rate=40,
    target_rate=65,
    justification_points=["6+ years experience", "Proven track record"]
)

Technical Architecture

MCP Communication Flow

Client (freelance_client.py) 
    ↕️ (stdio transport)
Server (freelance_server.py)
    ↕️ (LLM calls)
ChatGroq API (Langchain integration)

Server Capabilities

• Tools: 10+ interactive tools for gig management

• Resources: Market data and profile access

• Prompts: Template-based interactions

• LLM Integration: ChatGroq for AI features

Client Features

• Async Communication: Full async/await support

• Error Handling: Comprehensive error recovery

• Demo Mode: Automated feature showcase

• Interactive Mode: Manual command interface

• Environment Validation: Setup verification

Troubleshooting

Common Issues

1. "ChatGroq not initialized" Error

# Make sure GROQ_API_KEY is set
python freelance_client.py --check-env
# Add your key to .env file
echo "GROQ_API_KEY=your_key_here" >> .env

2. "freelance_server.py not found" Error

# Make sure the server file is in the same directory
ls -la freelance_server.py
# Or adjust the path in freelance_client.py

3. Module Import Errors

# Install missing dependencies
pip install -r requirements.txt
# Or check what's missing
python freelance_client.py --check-env

4. Server Connection Issues

# Make sure server file is executable
python freelance_server.py stdio  # Test server directly
# Check for syntax errors in server file
python -m py_compile freelance_server.py

Debug Mode

Enable detailed logging by setting environment variable:

export MCP_DEBUG=1
python freelance_client.py --mode demo

Manual Server Testing

Test the server independently:

# Run server in stdio mode
python freelance_server.py stdio

# Run server with SSE transport
python freelance_server.py sse

# Run server with HTTP transport
python freelance_server.py streamable-http

Advanced Usage

Custom Configuration

Modify freelance_client.py to customize:

• Server connection parameters

• Demo scenarios and data

• Error handling behavior

• Output formatting

Integration with Claude Desktop (Recommended)

Step 1: Create Environment File

Create a .env file in your project directory:

# Windows
copy NUL .env

# Linux/Mac
touch .env

Add your API keys to .env:

GROQ_API_KEY=your_groq_api_key_here
MCP_AUTH_TOKEN=your_optional_auth_token
OWNER_COUNTRY_CODE=1
OWNER_PHONE_NUMBER=5551234567

Step 2: Get GROQ API Key

1. Visit Groq Console

2. Sign up or log in

3. Navigate to API Keys section

4. Create a new API key

5. Copy and paste it into your .env file

Step 3: Locate Claude Desktop Config

• Windows: %APPDATA%\Claude\claude_desktop_config.json

• Mac: ~/Library/Application Support/Claude/claude_desktop_config.json

• Linux: ~/.config/Claude/claude_desktop_config.json

Step 4: Update Claude Desktop Config

Open claude_desktop_config.json and add the freelance server configuration:

{
  "mcpServers": {
    "freelance": {
      "command": "uv",
      "args": [
        "run",
        "--with", "mcp",
        "--with", "python-dotenv",
        "--with", "langchain-groq",
        "--with", "pydantic",
        "/absolute/path/to/your/freelance_server.py",
        "stdio"
      ],
       "env": {
         "GROQ_API_KEY": "your_groq_api_key_here",
         "MCP_AUTH_TOKEN": "your_optional_auth_token",
         "OWNER_COUNTRY_CODE": "1",
         "OWNER_PHONE_NUMBER": "5551234567"
       }
    }
  }
}

Important Notes:

• Replace /absolute/path/to/your/freelance_server.py with the actual full path to your freelance_server.py file

• On Windows, use double backslashes: C:\\Users\\YourName\\MCPs\\freelance_server.py

• On Mac/Linux, use forward slashes: /Users/YourName/MCPs/freelance_server.py

• Replace all placeholder values with your actual API keys and phone number

Windows Example:

{
  "mcpServers": {
    "freelance": {
      "command": "C:\\Users\\YourName\\.local\\bin\\uv.EXE",
      "args": [
        "run",
        "--with", "mcp",
        "--with", "python-dotenv",
        "--with", "langchain-groq",
        "--with", "pydantic",
        "C:\\Users\\YourName\\MCPs\\mcp-server-1\\freelance_server.py",
        "stdio"
      ],
      "env": {
         "GROQ_API_KEY": "gsk_xxxxxxxxxxxxxxxxxxxxx",
         "MCP_AUTH_TOKEN": "your_optional_auth_token",
         "OWNER_COUNTRY_CODE": "1",
         "OWNER_PHONE_NUMBER": "5551234567"
      }
    }
  }
}

Step 5: Restart Claude Desktop

1. Completely quit Claude Desktop (not just close the window)

2. Reopen Claude Desktop

3. The freelance server should now be available

Step 6: Verify Installation

In Claude Desktop, try asking:

• "Search for Python freelance gigs under $500"

• "Show me current freelance market trends"

• "Validate the owner phone number"

Troubleshooting Claude Desktop Integration:

1. Server shows as "failed":

   • Check the logs: Open the "Open Logs Folder" from the error

   • Look for ModuleNotFoundError - means dependencies are missing

   • Verify all --with packages are included in args

2. "Server disconnected" error:

   • Ensure stdio is the last argument in args array

   • Check that the path to freelance_server.py is absolute and correct

   • Verify uv is installed: Run uv --version in terminal

3. Environment variables not loading:

   • Double-check the .env file exists in the same directory as freelance_server.py

   • Verify env values in claude_desktop_config.json match your .env file

   • Make sure there are no extra quotes or spaces

4. Finding uv path (Windows):

   where.exe uv

5. Finding uv path (Mac/Linux):

   which uv

Alternative: Manual Installation Method

If you prefer to install dependencies globally instead of using --with flags:

# Install dependencies globally with uv
uv pip install mcp python-dotenv langchain-groq pydantic

# Then use simpler config
{
  "mcpServers": {
    "freelance": {
      "command": "uv",
      "args": [
        "run",
        "/path/to/freelance_server.py",
        "stdio"
      ],
      "env": {
        "GROQ_API_KEY": "your_key_here",
        "OWNER_COUNTRY_CODE": "1",
        "OWNER_PHONE_NUMBER": "5551234567"
      }
    }
  }
}

Integration with ngrok for Remote Access

If you want to access your MCP server remotely via HTTPS:

# 1. Download and install ngrok
# Visit: https://ngrok.com/download

# 2. Add your authtoken (sign up at ngrok.com to get one)
ngrok config add-authtoken <your_token>

# 3. Start your MCP server on a specific port
python freelance_server.py sse --port 8080

# 4. In another terminal, expose it with ngrok
ngrok http 8080

# 5. Use the provided HTTPS URL to connect remotely
# Example: https://abc123.ngrok.io

Note: For production use, consider implementing proper authentication and security measures.

API Extensions

The client can be extended to:

• Connect to live freelance platform APIs

• Integrate with local databases

• Add custom analysis tools

• Support additional LLM providers

Performance Notes

• First run may be slower due to server startup

• LLM calls require internet connection and API credits

• Code review processes files up to 50MB

• Concurrent gig searches are supported

• Server maintains in-memory cache for demos

Security Considerations

• API keys are loaded from environment variables only

• File operations are sandboxed to current directory

• No sensitive data is logged

• Server runs in isolated process

• Backup files include timestamps for safety

Available MCP Tools

Once integrated with Claude Desktop, you'll have access to these tools:

🔍 Search & Discovery

• search_gigs - Search for freelance gigs by skills, budget, project type, and platform

• validate - Validate server owner's phone number

👤 Profile Management

• create_user_profile - Create a new freelancer profile with skills and rates

• analyze_profile_fit - Analyze how well a profile matches a specific gig

• optimize_profile - Get AI-powered profile optimization recommendations

📝 Proposals & Negotiation

• generate_proposal - Generate personalized proposals using AI

• negotiate_rate - Get rate negotiation strategies and messages

💻 Code Tools

• code_review - Review code quality with metrics and suggestions

• code_debug - Debug and automatically fix code issues

📊 Tracking

• track_application_status - Track and analyze application performance

📚 Resources

• freelance://profile/{profile_id} - Access user profile data

• freelance://gigs/{platform} - Get gigs from specific platforms

• freelance://market-trends - View current market trends and insights

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

License

This project is open source and available under the MIT License.

Support

For issues, questions, or contributions, please visit the GitHub repository.