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

🚀 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

• **Win