mercari-jp

This MCP server implements a Mercari Japan (mercari-jp) marketplace interface that can be accessed via the MCP protocol. After starting the server in development mode, you can connect to it using an MCP client or MCP Inspector to issue standardized tool queries and receive structured responses from Mercari JP data. The repository demonstrates two entry points you can test locally: running the main server logic (server.py) and running a check utility (check_server.py) to input queries, keywords, and price ranges for testing. Use the MCP client to send requests to the mercari-jp server, and you should be able to filter by keywords and price constraints, with results returned in the MCP-friendly format.

To test locally, start the server in development mode with MCP tooling, then use the provided check script to simulate queries and verify tool capabilities. When integrating with Claude for Desktop or other clients, configure the mcpServers block so that the client knows to invoke uv run server.py in the project directory, and ensure the working directory is correctly set if you are using external tooling or editors that load configuration files.

Prerequisites:

• Python 3.11 or higher
• Access to uv (uvx) to manage Python environments
• Git

Installation steps:

1. Clone the repository git clone https://github.com/msr2903/mercari-jp-mcp.git cd mercari-jp-mcp

2. Create and activate a virtual environment using uv, then install the package in editable mode uv venv source .venv/bin/activate # On Windows: .venv\Scripts\activate uv pip install -e .

3. Run the server in development mode for testing uv run server.py

4. Optional: run the check script to test inputs uv run check_server.py

Notes:

• If you are on Windows, you may need Microsoft C++ Build Tools installed to compile any native dependencies.
• The project requires dependencies listed in pyproject.toml (including mcp, mercari, pydantic). Installing in editable mode ensures you are running the local development version.

Tips and common issues:

• Ensure you are using Python 3.11+ as required by the project.
• When using Claude for Desktop integration, you may need to provide absolute paths in configuration files and ensure the uv executable is accessible from your environment.
• If the server fails to start due to missing dependencies, run uv pip install -e . again after activating the virtual environment.
• For Windows users, ensure you have the Visual C++ Build Tools installed to compile native dependencies when needed.
• The README mentions testing with MCP Inspector and a separate check_server utility; use these to validate keyword filtering and price range capabilities before going into production.