remotolist-mcp

AI-powered semantic search for candidates. Use Claude Desktop to find tech talent with natural language queries.

⚡ Quick Start (one command):

npx remotolist-mcp setup

Follow the interactive wizard and you're done!

Table of Contents

• What is This?
• Features
• Installation & Setup
  • Prerequisites
  • Easy Setup (Recommended)
  • Manual Setup (Alternative)
• Usage
  • Available Tools
• CLI Commands
• Configuration
  • Configuration Locations
• Telemetry
• Troubleshooting
• Development & Local Testing
  • Using Local Development Server
  • Project Structure
  • Building from Source
• How It Works
• API Key Security
• Contributing
• Code of Conduct
• Support
• License
• Changelog

What is This?

This package connects Claude Desktop to the RemotoList MCP Server - an AI-powered candidate search engine built on semantic search and vector embeddings.

With this, you can ask Claude things like:

"Find me senior TypeScript developers with React experience" "Show me fullstack developers who speak English and are available immediately" "Find candidates with DevOps skills and AWS certification"

Claude will search through the RemotoList database using natural language understanding to find the perfect candidates.

Features

• 🤖 AI-Powered Search: Natural language queries for candidates
• ⚡ Easy Setup: Interactive wizard, no environment variables needed
• 🔒 Secure: API keys stored locally with proper permissions
• 🔄 Flexible: Works with production (remotolist.com) or local development
• 📊 Telemetry: Anonymous usage tracking (opt-in) to help improve
• 🔧 CLI Tools: Commands for testing, diagnostics, and management

Installation & Setup

Prerequisites

• Node.js 18+ (or just npx)
• Claude Desktop (latest version)
• RemotoList Account with an MCP API Key

Easy Setup (Recommended)

# One command setup (using npx)
npx remotolist-mcp setup

# Or install globally first
npm install -g remotolist-mcp
remotolist-mcp setup

The interactive wizard will:

1. Ask for your API key
2. Automatically use production server (https://remotolist.com/mcp/sse/)
3. Configure Claude Desktop automatically
4. No environment variables needed!

For development/local testing, use the --dev flag:

npx remotolist-mcp setup --dev
# This uses: http://localhost:8000/mcp/sse/

Manual Setup (Alternative)

If you prefer manual setup:

1. Install globally (optional but recommended):

   npm install -g remotolist-mcp

2. Get your API Key:

   • Visit: https://remotolist.com/recruiters/mcp/
   • Copy your MCP API Key (starts with cj_mcp_)

3. Run setup wizard:

   # Using npx (no installation needed)
   npx remotolist-mcp setup
      
   # Or if installed globally
   remotolist-mcp setup

4. Follow the prompts:

   • Enter your API key
   • The wizard automatically selects the server URL (production by default)
   • The wizard configures Claude Desktop automatically
   • (Add --dev flag if using local development server)

5. Restart Claude Desktop

Usage

Once configured, just use Claude normally:

Claude: What can I help you with?

You: Search for Python developers with Django experience

Claude: I'll search for Python developers with Django experience for you...
[Uses the RemotoList MCP search tool]

Available Tools

• search_candidates - Search candidates with natural language queries

  • Example: "Find Python developers with 3+ years experience"
  • Returns: Matching candidates with username, skills, timezone, salary expectations, availability

• get_candidate_profile - Get detailed information about a specific candidate

  • Example: "Show me the full profile for candidate 123"
  • Returns: Complete professional profile with experience, education, projects, languages, etc.

• get_candidate_profile_url - Get direct link to candidate's public profile

  • Example: "Give me the profile URL for candidate 123"
  • Returns: Direct link to https://remotolist.com/@username

Privacy & GDPR Compliance

✅ This tool is fully GDPR-compliant:

• Only searches public profiles (candidates who opted in)
• Uses professional identifiers (@username) instead of real names
• Never exposes personal data (emails, contact info, photos)
• Only public information is shared with AI services
• Candidates can opt-out instantly by making their profile private

CLI Commands

# Using npx (no installation needed)
npx remotolist-mcp [command]

# Or install globally first
npm install -g remotolist-mcp
remotolist-mcp [command]

# Commands:
# Interactive setup wizard (uses production server)
npx remotolist-mcp setup

# Setup for local development (uses localhost)
npx remotolist-mcp setup --dev
npx remotolist-mcp setup --local

# Show current configuration
npx remotolist-mcp config

# Test connection to RemotoList
npx remotolist-mcp test

# Diagnose and fix issues
npx remotolist-mcp doctor

# Manage telemetry settings
npx remotolist-mcp telemetry --enable
npx remotolist-mcp telemetry --disable

# Show help
npx remotolist-mcp help

Configuration

Configuration is stored in ~/.remotolist/config.json:

{
  "apiKey": "cj_mcp_...",
  "sseUrl": "https://remotolist.com/mcp/sse/",
  "version": "1.0.0",
  "installationId": "uuid-v4",
  "createdAt": "2025-03-12T10:30:00Z",
  "lastUpdated": "2025-03-12T10:30:00Z",
  "telemetryOptIn": true
}

Configuration Locations

• Main config: ~/.remotolist/config.json
• Claude Desktop: Automatically configured during setup
• Telemetry preferences: ~/.remotolist/telemetry-opt-in.json

Telemetry

RemotoList MCP includes optional anonymous telemetry to help improve the product.

We track:

• Installation and setup events
• Error types (not messages)
• Usage counts (not content)
• Platform information (OS, version)

We do NOT track:

• Your search queries or candidate data
• Personal information
• API keys or sensitive data
• Specific error messages

To manage telemetry:

# Enable telemetry
npx remotolist-mcp telemetry --enable

# Disable telemetry
npx remotolist-mcp telemetry --disable

# Check status
npx remotolist-mcp telemetry

Troubleshooting

"Configuration not found"

# Run the setup wizard
npx remotolist-mcp setup

"Claude Desktop not found"

1. Install Claude Desktop from https://claude.ai/desktop
2. Run npx remotolist-mcp setup again

"Invalid API key"

1. Get a new API key from https://remotolist.com/recruiters/mcp/
2. Run npx remotolist-mcp setup to update

"Connection failed"

# Test connection
npx remotolist-mcp test

# Run diagnostics
npx remotolist-mcp doctor

"MCP server not showing in Claude"

1. Make sure Claude Desktop is restarted
2. Run npx remotolist-mcp doctor to check configuration
3. Check Claude config file for errors

Development & Local Testing

Using Local Development Server

For local development and testing, use the --dev flag during setup:

# Setup for local development
npx remotolist-mcp setup --dev

# This automatically configures to use: http://localhost:8000/mcp/sse/

Note: The --dev flag is intended for development team members only. Regular users should use the standard setup without the flag.

Project Structure

src/
├── index.ts              # Main entry point
├── config-manager.ts     # Configuration management
├── claude-config.ts      # Claude Desktop integration
├── wizard.ts             # Interactive setup wizard
├── api-key-validator.ts  # API key validation
├── telemetry.ts          # Anonymous usage tracking
├── commands.ts           # CLI commands
├── bridge.ts             # SSE bridge to RemotoList
└── config.ts             # Legacy config (deprecated)

Building from Source

# Clone the repository
git clone https://github.com/roylans/remotolist-mcp.git
cd remotolist-mcp

# Install dependencies
npm install

# Build TypeScript
npm run build

# Test locally
node dist/index.js setup

How It Works

Claude Desktop
    ↓ (JSON-RPC messages via stdio)
    ↓
remotolist-mcp (this package)
    ↓ (SSE over HTTPS with API key)
    ↓
RemotoList MCP Server (Django backend)
    ↓ (Semantic search with Qdrant)
    ↓
Vector Database (embeddings)
    ↓
Candidate Results
    ↓
Claude Desktop (response to user)

This architecture ensures:

• ✅ Secure - HTTPS with API key authentication
• ✅ Fast - Semantic search with vector embeddings
• ✅ Scalable - Centralized backend handles all candidates
• ✅ Updated - Candidate data always current
• ✅ Private - Your queries stay between you and RemotoList

API Key Security

🔐 Best Practices:

1. ✅ Store in configuration file - Automatically handled by setup wizard
2. ✅ File permissions - Config files have 600 permissions (owner read/write only)
3. ✅ Rotate regularly - Generate new keys in dashboard
4. ✅ Revoke old keys - From dashboard when no longer needed
5. ❌ Never commit keys to git
6. ❌ Never share keys in screenshots or emails

Contributing

We welcome contributions! Here's how you can help:

Reporting Issues

• Check if the issue already exists in the GitHub Issues
• Provide detailed information: OS, Node.js version, error messages, steps to reproduce

Feature Requests

• Open an issue with the "enhancement" label
• Describe the use case and expected behavior

Pull Requests

1. Fork the repository
2. Create a feature branch: git checkout -b feature/amazing-feature
3. Make your changes
4. Run tests: npm test
5. Ensure code quality: npm run lint
6. Commit with descriptive messages
7. Push to your fork
8. Open a Pull Request

Development Setup

# Clone and install
git clone https://github.com/roylans/remotolist-mcp.git
cd remotolist-mcp
npm install

# Build
npm run build

# Run tests
npm test

# Lint code
npm run lint

Code Style

• Use TypeScript with strict mode
• Follow existing code patterns
• Add tests for new features
• Update documentation
• Keep commits focused and atomic

Code of Conduct

Our Pledge

We pledge to make participation in our project a harassment-free experience for everyone.

Our Standards

• Using welcoming and inclusive language
• Being respectful of differing viewpoints
• Gracefully accepting constructive criticism
• Focusing on what is best for the community

Enforcement

Instances of abusive behavior may be reported to the project maintainers. All complaints will be reviewed and investigated.

Support

• 📖 Documentation: https://docs.remotolist.com/mcp
• 🐛 Report bugs: https://github.com/roylans/remotolist-mcp/issues
• 💬 Discord: https://discord.gg/remotolist
• 📧 Email: [email protected]

License

MIT License © 2025 RemotoList. See LICENSE file for details.

Changelog

v1.0.0 (2025-03-12)

• ✨ Complete rewrite with interactive setup wizard
• ✅ No environment variables required
• 🔧 Automatic Claude Desktop configuration
• 📊 Optional anonymous telemetry
• 🩺 Diagnostic tools (doctor command)
• 🚀 One-command installation: npx remotolist-mcp setup

Happy recruiting! 🚀