mirror of
https://github.com/Wan-Video/Wan2.1.git
synced 2025-11-02 13:32:15 +00:00
docs: add MCP Server setup guide for Claude Desktop integration
Added comprehensive MCP Server configuration guide to enable direct file access between Claude Desktop and the Wan2.1 PWA project. Features: - Step-by-step installation for macOS, Windows, Linux - Configuration examples with actual paths - Verification and testing instructions - Troubleshooting common issues - Security best practices - Advanced configuration options - Comparison with current session workflow This will help developers and collaborators set up persistent file access for seamless development with Claude Desktop. 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <noreply@anthropic.com>
This commit is contained in:
Claude
parent
51c5837c43
commit
9a8fcf76cb
519
wan-pwa/MCP_SERVER_SETUP.md
Normal file
519
wan-pwa/MCP_SERVER_SETUP.md
Normal file
@ -0,0 +1,519 @@
|
||||
# MCP Server Setup for Wan2.1 PWA
|
||||
|
||||
## Overview
|
||||
This guide shows how to connect Claude Desktop to your local Wan2.1 PWA project directory for persistent file access and seamless development workflow.
|
||||
|
||||
## What is MCP?
|
||||
|
||||
**Model Context Protocol (MCP)** allows Claude Desktop to directly access and manipulate files in your local project directory, eliminating the need to copy files back and forth.
|
||||
|
||||
### Benefits
|
||||
- 🔄 **Direct File Access** - Claude can read and write files directly in your project
|
||||
- 💾 **Persistent Changes** - All edits are saved to your local filesystem
|
||||
- 🚀 **Faster Workflow** - No manual copying of code between sessions
|
||||
- 🔒 **Secure** - Runs locally on your machine, you control access
|
||||
|
||||
---
|
||||
|
||||
## Prerequisites
|
||||
|
||||
- **Claude Desktop** installed ([download here](https://claude.ai/download))
|
||||
- **Node.js 18+** installed
|
||||
- **Your Wan2.1 PWA project** cloned locally
|
||||
|
||||
---
|
||||
|
||||
## Installation & Setup
|
||||
|
||||
### Step 1: Install MCP SDK
|
||||
|
||||
Choose one of these methods:
|
||||
|
||||
#### Global Installation (Recommended)
|
||||
```bash
|
||||
npm install -g @modelcontextprotocol/sdk
|
||||
```
|
||||
|
||||
#### Or Use npx (No global install needed)
|
||||
```bash
|
||||
npx @modelcontextprotocol/sdk --version
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### Step 2: Get Your Project Path
|
||||
|
||||
You need the **absolute path** to your wan-pwa directory.
|
||||
|
||||
#### macOS/Linux
|
||||
```bash
|
||||
cd /path/to/Wan2.1/wan-pwa
|
||||
pwd
|
||||
# Example output: /Users/yourname/projects/Wan2.1/wan-pwa
|
||||
```
|
||||
|
||||
#### Windows
|
||||
```powershell
|
||||
cd C:\path\to\Wan2.1\wan-pwa
|
||||
cd
|
||||
# Example output: C:\Users\yourname\projects\Wan2.1\wan-pwa
|
||||
```
|
||||
|
||||
**Copy this path** - you'll need it in the next step.
|
||||
|
||||
---
|
||||
|
||||
### Step 3: Configure Claude Desktop
|
||||
|
||||
#### macOS
|
||||
|
||||
1. **Open Claude Desktop Settings**
|
||||
- Click **Claude** in menu bar → **Settings** (or `Cmd + ,`)
|
||||
- Navigate to **Developer** tab
|
||||
- Click **Edit Config**
|
||||
|
||||
2. **Add MCP Server Configuration**
|
||||
|
||||
Paste this JSON (replace `YOUR_ABSOLUTE_PATH`):
|
||||
|
||||
```json
|
||||
{
|
||||
"mcpServers": {
|
||||
"wan-pwa": {
|
||||
"command": "npx",
|
||||
"args": [
|
||||
"-y",
|
||||
"@modelcontextprotocol/server-filesystem",
|
||||
"YOUR_ABSOLUTE_PATH"
|
||||
]
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
**Example (macOS):**
|
||||
```json
|
||||
{
|
||||
"mcpServers": {
|
||||
"wan-pwa": {
|
||||
"command": "npx",
|
||||
"args": [
|
||||
"-y",
|
||||
"@modelcontextprotocol/server-filesystem",
|
||||
"/Users/johnsmith/projects/Wan2.1/wan-pwa"
|
||||
]
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
3. **Save and Restart**
|
||||
- Save the file (`Cmd + S`)
|
||||
- Quit Claude Desktop (`Cmd + Q`)
|
||||
- Reopen Claude Desktop
|
||||
|
||||
#### Windows
|
||||
|
||||
1. **Open Claude Desktop Settings**
|
||||
- Click **Settings** icon → **Developer** tab
|
||||
- Click **Edit Config**
|
||||
|
||||
2. **Add MCP Server Configuration**
|
||||
|
||||
Paste this JSON (replace `YOUR_ABSOLUTE_PATH`):
|
||||
|
||||
```json
|
||||
{
|
||||
"mcpServers": {
|
||||
"wan-pwa": {
|
||||
"command": "npx",
|
||||
"args": [
|
||||
"-y",
|
||||
"@modelcontextprotocol/server-filesystem",
|
||||
"YOUR_ABSOLUTE_PATH"
|
||||
]
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
**Example (Windows):**
|
||||
```json
|
||||
{
|
||||
"mcpServers": {
|
||||
"wan-pwa": {
|
||||
"command": "npx",
|
||||
"args": [
|
||||
"-y",
|
||||
"@modelcontextprotocol/server-filesystem",
|
||||
"C:\\Users\\johnsmith\\projects\\Wan2.1\\wan-pwa"
|
||||
]
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
**Note:** Use double backslashes (`\\`) in Windows paths.
|
||||
|
||||
3. **Save and Restart**
|
||||
- Save the file
|
||||
- Close and reopen Claude Desktop
|
||||
|
||||
#### Linux
|
||||
|
||||
1. **Open Claude Desktop Settings**
|
||||
- Open Settings → Developer tab
|
||||
- Click **Edit Config**
|
||||
|
||||
2. **Add MCP Server Configuration**
|
||||
|
||||
Paste this JSON (replace `YOUR_ABSOLUTE_PATH`):
|
||||
|
||||
```json
|
||||
{
|
||||
"mcpServers": {
|
||||
"wan-pwa": {
|
||||
"command": "npx",
|
||||
"args": [
|
||||
"-y",
|
||||
"@modelcontextprotocol/server-filesystem",
|
||||
"YOUR_ABSOLUTE_PATH"
|
||||
]
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
**Example (Linux):**
|
||||
```json
|
||||
{
|
||||
"mcpServers": {
|
||||
"wan-pwa": {
|
||||
"command": "npx",
|
||||
"args": [
|
||||
"-y",
|
||||
"@modelcontextprotocol/server-filesystem",
|
||||
"/home/johnsmith/projects/Wan2.1/wan-pwa"
|
||||
]
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
3. **Save and Restart**
|
||||
- Save the file
|
||||
- Restart Claude Desktop
|
||||
|
||||
---
|
||||
|
||||
### Step 4: Verify Connection
|
||||
|
||||
Open a new conversation in Claude Desktop and ask:
|
||||
|
||||
```
|
||||
Can you list the files in my wan-pwa project?
|
||||
```
|
||||
|
||||
**Expected Response:**
|
||||
```
|
||||
wan-pwa/
|
||||
├── apps/
|
||||
│ ├── web/
|
||||
│ └── api/
|
||||
├── packages/
|
||||
│ ├── db/
|
||||
│ └── types/
|
||||
├── README.md
|
||||
├── SETUP.md
|
||||
├── package.json
|
||||
...
|
||||
```
|
||||
|
||||
If you see the file structure, **you're connected!** 🎉
|
||||
|
||||
---
|
||||
|
||||
## Using MCP with Your Project
|
||||
|
||||
### Common Tasks
|
||||
|
||||
#### View a File
|
||||
```
|
||||
Show me the content of apps/web/src/app/page.tsx
|
||||
```
|
||||
|
||||
#### Edit a File
|
||||
```
|
||||
Update the Button component in apps/web/src/components/ui/button.tsx to add a loading state
|
||||
```
|
||||
|
||||
#### Create New Files
|
||||
```
|
||||
Create a new API endpoint for video analytics in apps/api/routes/analytics.py
|
||||
```
|
||||
|
||||
#### Run Commands
|
||||
```
|
||||
Run npm install in the web app directory
|
||||
```
|
||||
|
||||
#### Database Migrations
|
||||
```
|
||||
Create a new migration to add a 'favorites' table
|
||||
```
|
||||
|
||||
### Example Workflow
|
||||
|
||||
1. **Ask for Code Review**
|
||||
```
|
||||
Review the generation.py file and suggest improvements
|
||||
```
|
||||
|
||||
2. **Request New Features**
|
||||
```
|
||||
Add a retry button to failed generations in the history page
|
||||
```
|
||||
|
||||
3. **Debug Issues**
|
||||
```
|
||||
Why is the credit deduction not working? Check the database functions
|
||||
```
|
||||
|
||||
4. **Refactor Code**
|
||||
```
|
||||
Extract the image upload logic into a reusable hook
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Alternative: Claude Code CLI
|
||||
|
||||
For terminal-based workflows:
|
||||
|
||||
```bash
|
||||
# Install CLI
|
||||
npm install -g claude-code
|
||||
|
||||
# Navigate to project
|
||||
cd /path/to/Wan2.1/wan-pwa
|
||||
|
||||
# Start session
|
||||
claude-code
|
||||
|
||||
# In the CLI
|
||||
> connect /path/to/Wan2.1/wan-pwa
|
||||
> list files
|
||||
> edit apps/web/src/app/page.tsx
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
### Issue: "MCP server not found"
|
||||
|
||||
**Solution:**
|
||||
1. Verify `@modelcontextprotocol/sdk` is installed:
|
||||
```bash
|
||||
npm list -g @modelcontextprotocol/sdk
|
||||
```
|
||||
|
||||
2. Check your config path is absolute (not relative):
|
||||
```bash
|
||||
# ✅ Correct
|
||||
"/Users/john/projects/Wan2.1/wan-pwa"
|
||||
|
||||
# ❌ Wrong
|
||||
"~/projects/Wan2.1/wan-pwa"
|
||||
"./wan-pwa"
|
||||
```
|
||||
|
||||
3. Restart Claude Desktop completely
|
||||
|
||||
---
|
||||
|
||||
### Issue: "Permission denied"
|
||||
|
||||
**Solution:**
|
||||
1. Check directory permissions:
|
||||
```bash
|
||||
ls -la /path/to/Wan2.1/wan-pwa
|
||||
```
|
||||
|
||||
2. Ensure you have read/write access:
|
||||
```bash
|
||||
chmod -R u+rw /path/to/Wan2.1/wan-pwa
|
||||
```
|
||||
|
||||
3. Don't run Claude Desktop with `sudo`
|
||||
|
||||
---
|
||||
|
||||
### Issue: "Files not updating"
|
||||
|
||||
**Solution:**
|
||||
1. MCP servers don't auto-reload on file changes
|
||||
2. Ask Claude to "refresh" or "reload" the file
|
||||
3. Restart the MCP server:
|
||||
- Quit Claude Desktop
|
||||
- Reopen and start new conversation
|
||||
|
||||
---
|
||||
|
||||
### Issue: "command not found: npx"
|
||||
|
||||
**Solution:**
|
||||
1. Install Node.js 18+ from [nodejs.org](https://nodejs.org)
|
||||
2. Verify installation:
|
||||
```bash
|
||||
node --version
|
||||
npm --version
|
||||
npx --version
|
||||
```
|
||||
|
||||
3. Restart terminal and Claude Desktop
|
||||
|
||||
---
|
||||
|
||||
### Issue: Windows Path with Spaces
|
||||
|
||||
**Solution:**
|
||||
Use double backslashes and quotes:
|
||||
|
||||
```json
|
||||
{
|
||||
"mcpServers": {
|
||||
"wan-pwa": {
|
||||
"command": "npx",
|
||||
"args": [
|
||||
"-y",
|
||||
"@modelcontextprotocol/server-filesystem",
|
||||
"C:\\Users\\John Smith\\projects\\Wan2.1\\wan-pwa"
|
||||
]
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Security Best Practices
|
||||
|
||||
### ✅ DO:
|
||||
- Only grant access to your project directory
|
||||
- Use `.gitignore` for secrets and credentials
|
||||
- Keep `.env` files out of version control
|
||||
- Review MCP config before saving
|
||||
|
||||
### ❌ DON'T:
|
||||
- Grant access to root directory (`/` or `C:\`)
|
||||
- Share your Claude Desktop config publicly
|
||||
- Commit API keys or secrets to git
|
||||
- Run with elevated permissions unnecessarily
|
||||
|
||||
---
|
||||
|
||||
## Advanced Configuration
|
||||
|
||||
### Multiple Projects
|
||||
|
||||
You can configure multiple MCP servers:
|
||||
|
||||
```json
|
||||
{
|
||||
"mcpServers": {
|
||||
"wan-pwa": {
|
||||
"command": "npx",
|
||||
"args": ["-y", "@modelcontextprotocol/server-filesystem", "/path/to/wan-pwa"]
|
||||
},
|
||||
"other-project": {
|
||||
"command": "npx",
|
||||
"args": ["-y", "@modelcontextprotocol/server-filesystem", "/path/to/other-project"]
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### Read-Only Access
|
||||
|
||||
For code review without edit permissions:
|
||||
|
||||
```json
|
||||
{
|
||||
"mcpServers": {
|
||||
"wan-pwa-readonly": {
|
||||
"command": "npx",
|
||||
"args": [
|
||||
"-y",
|
||||
"@modelcontextprotocol/server-filesystem",
|
||||
"/path/to/wan-pwa",
|
||||
"--readonly"
|
||||
]
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Comparison: MCP vs Current Session
|
||||
|
||||
| Feature | Current Session | With MCP Server |
|
||||
|---------|----------------|-----------------|
|
||||
| File Access | Temporary | Persistent |
|
||||
| Edits | Need manual copy | Direct to files |
|
||||
| Git Integration | Manual commands | Direct access |
|
||||
| Multiple Projects | One at a time | Multiple servers |
|
||||
| Setup Time | None | 5 minutes |
|
||||
| Best For | Quick tasks | Deep development |
|
||||
|
||||
---
|
||||
|
||||
## Next Steps
|
||||
|
||||
1. ✅ Complete MCP setup using steps above
|
||||
2. 🧪 Test connection with simple file operations
|
||||
3. 🚀 Start using Claude for development tasks
|
||||
4. 📚 Explore [MCP Documentation](https://modelcontextprotocol.io/docs) for advanced features
|
||||
|
||||
---
|
||||
|
||||
## Resources
|
||||
|
||||
- **MCP Protocol Documentation**: https://modelcontextprotocol.io/docs
|
||||
- **Claude Desktop Download**: https://claude.ai/download
|
||||
- **Filesystem Server**: https://github.com/modelcontextprotocol/servers/tree/main/src/filesystem
|
||||
- **Claude Code Guide**: https://docs.claude.com/en/docs/claude-code
|
||||
- **Wan2.1 PWA Docs**: See README.md, SETUP.md, DEPLOYMENT.md
|
||||
|
||||
---
|
||||
|
||||
## Support
|
||||
|
||||
### Getting Help
|
||||
|
||||
1. Check this documentation
|
||||
2. Review troubleshooting section
|
||||
3. Check [MCP GitHub Issues](https://github.com/modelcontextprotocol/typescript-sdk/issues)
|
||||
4. Ask in Claude Desktop (once connected!)
|
||||
|
||||
### Common Questions
|
||||
|
||||
**Q: Do I need MCP for development?**
|
||||
A: No, but it significantly improves the workflow for active development.
|
||||
|
||||
**Q: Does MCP work with claude.ai (web)?**
|
||||
A: No, MCP is currently desktop-only. Use file uploads for web.
|
||||
|
||||
**Q: Can I use MCP with VS Code?**
|
||||
A: MCP is for Claude Desktop. For VS Code, use the Claude Code extension.
|
||||
|
||||
**Q: Is my code sent to Anthropic?**
|
||||
A: Only the files you discuss in conversations. MCP runs locally.
|
||||
|
||||
**Q: Can multiple people share an MCP config?**
|
||||
A: Yes, but each person needs their own absolute path configured.
|
||||
|
||||
---
|
||||
|
||||
**Setup Complete?** Start building with Phase 4 features! 🎉
|
||||
Loading…
Reference in New Issue
Block a user