brianstanley/mcp-server-mercado-libre

MercadoLibre MCP Server

I built this as a test project to explore Model Context Protocol (MCP) server integrations and web scraping. It's basically a server that lets AI assistants search for products in specific MercadoLibre stores programmatically.

Note: This is just a side project I made to test MCP server integrations and web scraping techniques. It's not meant for production use and has some limitations.

🎯 What it does

This server can:

• Search for products in specific MercadoLibre stores
• Extract product info like titles and prices
• Connect with AI assistants through the MCP protocol
• Scrape websites using Playwright
• Handle multiple sessions for different clients

What it can't do yet:

• Only gets basic info (title and price)
• Works with limited MercadoLibre URL formats
• No fancy filtering or sorting
• Pretty basic error handling

🏗️ Architecture

┌─────────────────┐    ┌──────────────────┐    ┌─────────────────┐
│   MCP Client    │───▶│  MCP Server      │───▶│  MercadoLibre   │
│   (AI Assistant)│    │  (Express + MCP) │    │  (Web Scraping) │
└─────────────────┘    └──────────────────┘    └─────────────────┘

Components

• MCP Server: Handles all the protocol stuff and registers tools
• Web Scraper: Uses Playwright to grab product data from MercadoLibre
• URL Transformer: Converts store URLs into search URLs
• Session Manager: Keeps track of different client connections

🚀 Quick Start

Prerequisites

• Node.js 20+
• Docker (if you want to deploy)
• Google Cloud account (for Cloud Run deployment)
• Some basic understanding of MCP protocol (helpful but not required)

Local Development

1. Clone the repository

   git clone <repository-url>
   cd mcp-server-scrap-ml
   

2. Install dependencies

   npm install
   

3. Start the server

   npm start
   

The server will be available at http://localhost:3003

Using Docker

1. Build the image

   docker build -t mcp-server .
   

2. Run the container

   docker run -p 3003:3003 mcp-server
   

🔧 How to Use

MCP Tool: search_mercadolibre

Right now the server has one tool for searching products:

Parameters

• query (string): Search terms (e.g., "smart watch", "laptop")
• store (string): MercadoLibre store URL

Example Usage

// Example MCP client call
const result = await mcpClient.callTool("search_mercadolibre", {
  query: "smart watch",
  store: "https://tienda.mercadolibre.com.ar/example-store"
});

Supported Store URL Formats

It works with these URL formats:

1. Tienda URLs:

   https://tienda.mercadolibre.com.ar/store-name
   

2. Pagina URLs:

   https://www.mercadolibre.com.ar/pagina/store-name
   

Note: Other MercadoLibre URL formats probably won't work with this version.

API Endpoints

• GET / - Health check
• POST /mcp - MCP client communication
• GET /mcp - Server-to-client notifications (SSE)
• DELETE /mcp - Session termination

🌐 Deployment

Deploy to Google Cloud Run

1. Set up Google Cloud CLI

   gcloud auth login
   gcloud config set project YOUR_PROJECT_ID
   

2. Enable required APIs

   gcloud services enable cloudbuild.googleapis.com
   gcloud services enable run.googleapis.com
   

3. Deploy using Cloud Build

   gcloud builds submit --config cloudbuild.yaml
   

The service will be deployed with:

• Public access (no authentication required)
• 1 CPU, 1GB RAM
• 0-10 instances (auto-scaling)
• 300s timeout

Access Your Deployed Service

After deployment, your service will be available at:

https://mcp-server-[PROJECT_ID].us-central1.run.app

📋 Configuration

Environment Variables

• PORT: Server port (default: 3003, Cloud Run sets this automatically)

Cloud Run Configuration

The service is configured with:

• Memory: 1GB
• CPU: 1 vCPU
• Max instances: 10
• Timeout: 300 seconds
• Public access: Enabled

🔍 How It Works

1. URL Transformation

The server takes store URLs and turns them into search URLs using some basic string manipulation:

// Input
store: "https://tienda.mercadolibre.com.ar/example-store"
query: "smart watch"

// Output
searchUrl: "https://listado.mercadolibre.com.ar/smart-watch_Tienda_example-store"

2. Web Scraping

Uses Playwright with Chromium (headless mode):

• Goes to the search URL
• Waits for the page to load
• Grabs product titles and prices using CSS selectors
• Returns the first 5 results (hardcoded limit)

3. MCP Integration

• Registers the search_mercadolibre tool with some basic validation
• Manages client sessions pretty simply
• Returns responses in MCP format

📊 Example Response

{
  "content": [
    {
      "type": "text",
      "text": "Smart Watch XYZ - $15000\nSmart Watch ABC - $12000\nSmart Watch DEF - $18000"
    }
  ]
}

🛠️ Development

Project Structure

src/
├── index.js              # Express server and MCP integration
├── config/
│   └── server.js         # MCP server configuration
├── services/
│   └── scraper.js        # Web scraping logic (pretty basic)
├── transport/
│   └── session.js        # Session management
└── utils/
    └── error.js          # Error handling utilities

Adding New Features

Since this is a test project, here's how you could add more stuff:

1. New MCP Tools: Add to src/config/server.js
2. Better Scraping: Extend src/services/scraper.js to get more data
3. More Endpoints: Modify src/index.js for new API routes
4. Better Error Handling: Improve validation and error responses
5. Rate Limiting: Add some protection against abuse

🔒 Security Considerations

⚠️ Important: This is a test project with pretty basic security:

• Public Access: The service is public (not great for production)
• No Rate Limiting: No protection against abuse
• Basic Input Validation: Uses Zod for some validation
• Limited Error Handling: Pretty basic error responses
• No Authentication: No user auth or authorization

For Production: You'd want to add proper security like authentication, rate limiting, and better input validation.

🐛 Troubleshooting

Common Issues

1. "Forbidden" Error: Try hard refresh or incognito mode
2. No Products Found: Check if the store URL format is supported
3. Timeout Errors: Increase timeout in Cloud Run configuration
4. Browser Issues: Ensure Playwright dependencies are installed

Logs

Check Cloud Run logs:

gcloud run services logs read mcp-server --region=us-central1

🤝 Contributing

This is just a personal test project, but feel free to reach out if you have any feedback or suggestions!

Note: This is a test project I made to explore MCP server integrations and web scraping. It's not meant for production use. Make sure to follow MercadoLibre's terms of service if you use it beyond just testing.