Windows Local Development Setup Issue - uvx Configuration Error

[riyas50]

Windows Local Development Setup Issue - uvx Configuration Error

Problem Description

When setting up Serena MCP for local development on Windows, users may encounter the following error:

× Failed to build `run==0.2`
├─▶ The build backend returned an error
╰─▶ Call to `setuptools.build_meta:__legacy__.build_wheel` failed (exit code: 1)
    [stderr]
    NameError: name 'file' is not defined
    
hint: `uvx run serena-mcp-server` invokes the `run` package. Did you mean `uvx serena-mcp-server`?

Root Cause

The issue occurs when using an incorrect uvx run syntax in the Claude Desktop configuration. The command uvx run serena-mcp-server attempts to invoke a package called run instead of running the local serena-mcp-server.

Environment

• OS: Windows
• Python: 3.13 (though Serena requires Python 3.11-3.12)
• Tool: uvx/uv
• Setup: Local repository clone

Solution

Option 1: Corrected uvx Configuration (Recommended)

Update your claude_desktop_config.json with this configuration:

"serena": {
  "command": "D:\\Python\\Python313\\Scripts\\uvx.exe",
  "args": [
    "--directory",
    "D:\\mcpservers\\serena",
    "serena-mcp-server"
  ]
}

Key changes:

• Remove the "run" argument
• Use --directory flag to specify the local repository path

Option 2: Using uv run

If Option 1 doesn't work, try using uv run instead:

"serena": {
  "command": "D:\\Python\\Python313\\Scripts\\uv.exe",
  "args": [
    "run",
    "--directory", 
    "D:\\mcpservers\\serena",
    "serena-mcp-server"
  ]
}

Prerequisites

Before using either configuration:

1. Clone the repository:

   git clone https://github.com/serena-ryder/serena.git D:\mcpservers\serena

2. Sync dependencies (this will download the correct Python version):

   cd D:\mcpservers\serena
   uv sync

What NOT to do

❌ Incorrect configuration (causes the error):

"serena": {
  "command": "D:\\Python\\Python313\\Scripts\\uvx.exe",
  "args": [
    "run",
    "serena-mcp-server"
  ]
}

❌ Incorrect with directory (also causes the error):

"serena": {
  "command": "D:\\Python\\Python313\\Scripts\\uvx.exe",
  "args": [
    "run",
    "--directory",
    "D:\\mcpservers\\serena",
    "serena-mcp-server"
  ]
}

Python Version Compatibility Note

Serena requires Python 3.11-3.12, not 3.13. The uv sync command will automatically download and use the correct Python version for the project, so you don't need to downgrade your system Python.

Verification

After applying the fix:

1. Restart Claude Desktop
2. Check that the serena MCP server connects without errors
3. Look for successful connection messages in the Claude Desktop logs

Additional Resources

• [MCP Debugging Documentation](https://modelcontextprotocol.io/docs/tools/debugging)
• [UV Documentation](https://docs.astral.sh/uv/)

---

Tested on Windows with Python 3.13 and uv 0.x

[MischaPanch]

The things that are in your "not to do" part are not in our installation introductions, and what the LLM recommended you to is is there. I suspect that you didn't fully follow our readme for setting up Serena.

Closing this, nothing to do on our side.

For the future, pls don't just copy paste something from an LLM as issue before double checking whether it can be solved by reading the readme

[riyas50]

Hi,
It was not a blind copy paste. Sometimes beginners like me struggle, I thought someone like me save time. Yes I might have missed out something and that ended up getting help from Claude Desktop itself. If you feel this is totally irrelevant, you can go ahead and remove this please.

[MischaPanch]

All good, just for the future pls add some personal lines describing the issue, and make sure to check the readme before raising it :).

Nothing wrong with using LLMs to help with reporting issues, but we don't want to get flooded by autogenerated things