Troubleshooting

Common issues and solutions for the MarketCheck MCP Server — server startup, connection problems, API errors, and data quality.

Quick solutions for the most common issues when running the MarketCheck MCP Server.

Server Won't Start

Symptom	Cause	Solution
`ModuleNotFoundError`	Dependencies not installed	Run `uv sync` or `pip install -e .`
Python version error	Python < 3.12	Install Python 3.12+
Import errors	Corrupted environment	Delete `.venv/` and run `uv sync` again

Symptom	Cause	Solution
Claude Desktop doesn't see the server	Config file error	Verify JSON syntax in `claude_desktop_config.json` and restart Claude Desktop
"Server not found"	Wrong path	Use absolute path to `server.py` in the configuration
HTTP mode not connecting	Port in use	Change port with `--port 8001` or stop the conflicting process
Hosted server not responding	Network or key issue	Verify your API key is active and test with `curl "https://api.marketcheck.com/mcp?api_key=YOUR_KEY"`

Symptom	Cause	Solution
401 Unauthorized	Invalid API key	Verify `MARKETCHECK_API_KEY` is set correctly
Empty search results	Mismatched filter values	Run a facets query first to discover exact valid values
429 Too Many Requests	Rate limit exceeded	Implement backoff between calls; contact support for tier upgrade
Timeout errors	Large result set or slow network	Reduce `rows`, add more filters, or increase timeout in client

Symptom	Cause	Solution
Missing fields in response	Token optimization	Set `include_dealer_object=true` or `include_build_object=true` as needed
Only one photo per listing	Default behavior	Set `fetch_all_photos=true` for full photo arrays
Type validation errors	LLM sending strings for numbers	The server handles this automatically; if persisting, report the specific tool and parameters

Running the server with the --debug flag produces verbose logs that help diagnose issues:

python server.py --debug

Include relevant log output when contacting support.