sysrqio/freelancermap-mcp

FreelancerMap MCP Server

A Model Context Protocol (MCP) server for searching freelance projects on freelancermap.de. This server enables AI assistants like Cursor to search and retrieve freelance project information with advanced filtering options.

🚀 Features

• Advanced Search: Search projects by keywords, skills, location, and more
• Location Filtering: Filter by countries and specific cities
• Remote Work Options: Specify remote work percentage (0-100%)
• Duration Filtering: Filter by project duration in months
• Skill Matching: Search for specific technologies and skills
• Pagination Support: Automatically fetch multiple pages of results
• No Authentication Required: Anonymous search only

📋 Requirements

• Node.js 18.0.0 or higher
• Cursor IDE or compatible MCP client

🛠️ Installation

Option 1: Install from GitHub (Recommended)

# Clone the repository
git clone https://github.com/yourusername/freelancermap-mcp.git
cd freelancermap-mcp

# Install dependencies
npm install

# Build the project
npm run build

Option 2: Install via npm (when published)

npm install -g freelancermap-mcp

🔧 Configuration

For Cursor IDE

Add the following configuration to your Cursor settings:

Windows/Linux: %APPDATA%\Cursor\User\globalStorage\cursor.mcp\mcp_config.json

macOS: ~/Library/Application Support/Cursor/User/globalStorage/cursor.mcp/mcp_config.json

{
  "mcpServers": {
    "freelancermap": {
      "command": "node",
      "args": ["/path/to/freelancermap-mcp/dist/index.js"],
      "env": {}
    }
  }
}

For Cursor CLI

Add to ~/.cursor/mcp.json:

{
  "mcpServers": {
    "freelancermap": {
      "command": "node",
      "args": ["/path/to/freelancermap-mcp/dist/index.js"],
      "env": {}
    }
  }
}

🎯 Usage

Once configured, you can use the MCP server in Cursor by asking questions like:

• "Find Python developer projects in Berlin"
• "Search for remote DevOps positions in Germany"
• "Get me the latest React projects with 6-month duration"
• "Find Cloud Engineer positions in Hamburg"

Available Parameters

• query (required): Search keywords or skills
• countries: Array of country names (e.g., ["Germany", "Austria"])
• locations: Array of specific cities or states
• remote: Remote work percentage (0-100)
• minDuration: Minimum project duration in months
• maxDuration: Maximum project duration in months
• skills: Array of specific skills or technologies
• maxResults: Maximum number of results (default: 50)
• autoFetchPages: Automatically fetch multiple pages (default: true)

🔍 Example Searches

Basic Search

"Find Python projects in Germany"

Advanced Search with Filters

"Search for DevOps positions in Berlin with 80% remote work and 6-month duration"

Skill-Based Search

"Find projects requiring Kubernetes, Docker, and Terraform skills"

🏗️ Development

Prerequisites

• Node.js 18+
• TypeScript
• Git

Setup Development Environment

# Clone the repository
git clone https://github.com/yourusername/freelancermap-mcp.git
cd freelancermap-mcp

# Install dependencies
npm install

# Start development mode (watch mode)
npm run dev

# Build for production
npm run build

# Test the server
npm test

Project Structure

freelancermap-mcp/
├── src/
│   ├── api/           # API client and search logic
│   ├── tools/         # MCP tool definitions
│   ├── types.ts       # TypeScript type definitions
│   └── index.ts       # Main server entry point
├── dist/              # Compiled JavaScript output
├── package.json       # Project configuration
├── tsconfig.json      # TypeScript configuration
└── README.md          # This file

🧪 Testing

Test the MCP server manually:

# Test tool listing
echo '{"jsonrpc": "2.0", "id": 1, "method": "tools/list", "params": {}}' | npm start

# Test search functionality
echo '{"jsonrpc": "2.0", "id": 2, "method": "tools/call", "params": {"name": "search_freelancermap_projects", "arguments": {"query": "Python", "countries": ["Germany"]}}}' | npm start

📊 Supported Countries

The server supports searching in the following countries:

• Germany (Deutschland)
• Austria (Österreich)
• Switzerland (Schweiz)
• United Kingdom (Großbritannien)
• USA (Vereinigte Staaten)
• Spain (Spanien)
• France (Frankreich)
• Hungary (Ungarn)
• Belgium (Belgien)
• Bulgaria (Bulgarien)
• Estonia (Estland)
• Canada (Kanada)
• Luxembourg (Luxemburg)
• Netherlands (Niederlande)
• Poland (Polen)
• Romania (Rumänien)
• Saudi Arabia (Saudi Arabien)

🚨 Troubleshooting

MCP Server Not Connecting

1. Check Node.js version: Ensure you're using Node.js 18.0.0 or higher
2. Verify path: Make sure the path in your MCP configuration is correct
3. Restart Cursor: Restart Cursor IDE after configuration changes
4. Check logs: Look for error messages in Cursor's developer console

Build Issues

# Clean and rebuild
rm -rf dist/
npm run build

Permission Issues

# Make the script executable
chmod +x dist/index.js

📝 License

This project is licensed under the MIT License - see the file for details.

🤝 Contributing

1. Fork the repository
2. Create a feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add some amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

📞 Support

If you encounter any issues or have questions:

1. Check the Issues page
2. Create a new issue with detailed information
3. Include error messages and your configuration

🔄 Changelog

Version 1.0.0

• Initial release
• Basic project search functionality
• Advanced filtering options
• Multi-page result fetching
• Support for major European countries

🙏 Acknowledgments

• freelancermap.de for providing the project data
• Model Context Protocol for the MCP specification
• Cursor for the amazing AI-powered IDE

Made with ❤️ for the freelance community