Using Serena with Claude Code on Windows

Introduction

I'm a Mac user,
but I recently had an opportunity to develop on Windows.
Since I heard Claude Code is now available,
I thought, "I'm going to go all out with development using this!" and installed it.

On Mac, I've been using Serena extensively.
https://github.com/oraios/serena?tab=readme-ov-file#claude-code

However, I ran into some trouble trying to use Serena on Windows,
so I'm documenting this as a memo.
It's a hassle to research it all over again later...

Environment

• Claude Code
• Windows 11
• VS Code

Versions are approximately the latest as of 2025-08-14.

Conclusion

Create a .bat and a .ps1 file, then add the .bat via mcp.

# run-serena.ps1
$proj = (Get-Location).Path
uvx --from git+https://github.com/oraios/serena `
  serena start-mcp-server `
  --context ide-assistant `
  --project "$proj"

@echo off
REM Always run with this folder as the current directory
cd /d "%~dp0"
powershell -NoProfile -ExecutionPolicy Bypass -File ".\run-serena.ps1"

Once created:

claude mcp remove serena  # If an old definition exists
claude mcp add serena .\run-serena.cmd

Installation Issues

I followed this article but ran into some trouble.

https://zenn.dev/acntechjp/articles/a3daf17083277f

First, on Windows, this installation command doesn't work.
It seems that the --from used by uvx gets tangled with PowerShell arguments and causes issues.

claude mcp add serena -- uvx --from git+https://github.com/oraios/serena serena-mcp-server --context ide-assistant --project (Get-Location)

claude mcp add ... sometimes fails to correctly pass through arguments following --.
Specifically, there is a bug where options such as -NoProfile or --from are interpreted as "unknown options" by the CLI.

Execution via Ps1 File

So, the question was: "How can I bypass the --from issue?"
I asked ChatGPT and solved it.
If PowerShell breaks because of --from, then why not just wrap PowerShell in a batch file?
That was the general idea.

So, I created this:

# run-serena.ps1
$proj = (Get-Location).Path
uvx --from git+https://github.com/oraios/serena `
  serena start-mcp-server `
  --context ide-assistant `
  --project "$proj"

In theory, adding this via claude mcp add should work fine, but reality wasn't that simple.

2. Bypassing the Execution Policy (ExecutionPolicy)
   Directly executing .ps1 files might be blocked due to PowerShell's ExecutionPolicy settings or "files downloaded from the internet" (MOTW).

So how do I bypass this?

Directly executing .ps1 files might be blocked due to PowerShell's ExecutionPolicy settings or "files downloaded from the internet" (MOTW).
By explicitly specifying powershell -ExecutionPolicy Bypass from the .cmd side, you can override this and run it safely.

Based on that, I also created a .cmd file.

# run-serena.cmd
@echo off
REM Always run with this folder as the current directory
cd /d "%~dp0"
powershell -NoProfile -ExecutionPolicy Bypass -File ".\run-serena.ps1"

When you use claude mcp add on this .cmd file, the Serena window launches and becomes ready for use.

Summary by GPT

Why wrap .ps1 in .cmd?

1. Avoid Claude CLI argument parsing issues

claude mcp add ... sometimes fails to correctly pass through arguments following --.
Specifically, there is a bug where options such as -NoProfile or --from are interpreted as "unknown options" by the CLI.
By bundling them into a .cmd file, Claude CLI recognizes it as a "simple executable file," preventing misinterpretation of arguments.

2. Bypass the Execution Policy (ExecutionPolicy)

Directly executing .ps1 files may be blocked due to PowerShell's ExecutionPolicy settings or "files obtained from the internet" (MOTW).
By explicitly specifying powershell -ExecutionPolicy Bypass from the .cmd side, you can override this and run it safely.

3. Measures for permission issues on network/sync drives

Files like .ps1 on network drives (e.g., M:\...) or synced folders might not be directly launchable due to security restrictions.
.cmd files are treated as standard executables, making them less susceptible to these restrictions.

4. Fix startup path and current directory

When calling a .ps1 file directly from Claude CLI, the current directory might change, and Get-Location may not return the intended path.
By using cd /d "%~dp0" in the .cmd file, you ensure the script is always executed starting from its location.

In Summary

• Prevent argument misinterpretation
• Bypass PowerShell Execution Policy
• Bypass restrictions on network/sync drives
• Fix execution directory

Since there are these four benefits, introducing this as a "wrapper method for stable startup in a Windows environment" makes the background easier to understand.