165 lines
3.8 KiB
Markdown
165 lines
3.8 KiB
Markdown
# Quick Start Guide
|
|
|
|
## 🚀 Get Started in 5 Minutes
|
|
|
|
### Step 1: Get Your Nextcloud App Password
|
|
|
|
1. Log into your Nextcloud instance
|
|
2. Go to **Settings** → **Security**
|
|
3. Scroll to "Devices & sessions"
|
|
4. Enter a name (e.g., "MCP Server") and click "Create new app password"
|
|
5. Copy the generated password
|
|
|
|
### Step 2: Configure the Server
|
|
|
|
Create a `.env` file in the project root:
|
|
|
|
```bash
|
|
cp .env.example .env
|
|
```
|
|
|
|
Edit `.env` with your details:
|
|
|
|
```env
|
|
NEXTCLOUD_URL=https://your-nextcloud.com
|
|
NEXTCLOUD_USERNAME=your-username
|
|
NEXTCLOUD_PASSWORD=paste-your-app-password-here
|
|
```
|
|
|
|
### Step 3: Build and Test
|
|
|
|
```bash
|
|
# Build the project
|
|
npm run build
|
|
|
|
# Test it works (Ctrl+C to exit)
|
|
npm run start
|
|
```
|
|
|
|
You should see: `Nextcloud MCP Server running on stdio`
|
|
|
|
### Step 4: Connect to Claude Desktop
|
|
|
|
Edit your Claude Desktop config:
|
|
|
|
**macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`
|
|
**Windows**: `%APPDATA%\Claude\claude_desktop_config.json`
|
|
|
|
Add this configuration (replace the path with your actual path):
|
|
|
|
```json
|
|
{
|
|
"mcpServers": {
|
|
"nextcloud": {
|
|
"command": "node",
|
|
"args": ["/full/path/to/nextcloud-mcp/build/index.js"],
|
|
"env": {
|
|
"NEXTCLOUD_URL": "https://your-nextcloud.com",
|
|
"NEXTCLOUD_USERNAME": "your-username",
|
|
"NEXTCLOUD_PASSWORD": "your-app-password"
|
|
}
|
|
}
|
|
}
|
|
}
|
|
```
|
|
|
|
**Important**: Use the full absolute path to the build/index.js file!
|
|
|
|
### Step 5: Restart Claude Desktop
|
|
|
|
Quit Claude Desktop completely and reopen it.
|
|
|
|
### Step 6: Test with Claude
|
|
|
|
Try these prompts in Claude:
|
|
|
|
```
|
|
"Show me my open tasks"
|
|
"What meetings do I have today?"
|
|
"List my recent notes"
|
|
"Show me my latest emails"
|
|
```
|
|
|
|
## ✅ Verification Checklist
|
|
|
|
Before asking Claude to use Nextcloud:
|
|
|
|
- [ ] Nextcloud URL is correct (HTTPS, no trailing slash)
|
|
- [ ] App password is correctly copied (no extra spaces)
|
|
- [ ] Required apps are installed:
|
|
- [ ] Tasks app
|
|
- [ ] Calendar app
|
|
- [ ] Notes app
|
|
- [ ] Mail app (if using email features)
|
|
- [ ] Full absolute path used in Claude Desktop config
|
|
- [ ] Claude Desktop has been restarted
|
|
|
|
## 🔧 Common Issues
|
|
|
|
### "Connection refused" or timeout
|
|
- Check your Nextcloud URL is accessible
|
|
- Verify you're using HTTPS
|
|
- Try accessing the URL in your browser
|
|
|
|
### "Authentication failed" or 401 error
|
|
- Regenerate a new app password
|
|
- Make sure there are no spaces before/after the password
|
|
- Try your username in lowercase
|
|
|
|
### "Calendar not found" or "Tasks not found"
|
|
- Check that you have at least one calendar created
|
|
- Verify the Tasks app is installed and has a task list
|
|
- See customization section in README for different calendar names
|
|
|
|
### Claude doesn't show Nextcloud tools
|
|
- Verify Claude Desktop config file syntax (use a JSON validator)
|
|
- Check the path to build/index.js is correct and absolute
|
|
- Look at Claude Desktop logs for errors
|
|
- Restart Claude Desktop after config changes
|
|
|
|
## 🎯 Next Steps
|
|
|
|
Once working:
|
|
1. Customize calendar/task list names in `src/index.ts` if needed
|
|
2. Add more tools as needed for your workflow
|
|
3. Check out the full README.md for advanced features
|
|
|
|
## 📚 Example Use Cases
|
|
|
|
**Task Management**:
|
|
```
|
|
"Create a task to review the integration docs, due tomorrow"
|
|
"Show me all my completed tasks this week"
|
|
"Mark task X as complete"
|
|
```
|
|
|
|
**Calendar**:
|
|
```
|
|
"What's on my calendar tomorrow?"
|
|
"Schedule a meeting with the team next Monday at 2pm"
|
|
"Show me my events for next week"
|
|
```
|
|
|
|
**Notes**:
|
|
```
|
|
"Create a note with my meeting notes from today"
|
|
"Show me all my notes"
|
|
"What's in note ID 123?"
|
|
```
|
|
|
|
**Email**:
|
|
```
|
|
"Show me my latest emails"
|
|
"What are my unread messages?"
|
|
```
|
|
|
|
## 🆘 Getting Help
|
|
|
|
If you're stuck:
|
|
1. Check the logs: `~/Library/Logs/Claude/mcp*.log` (macOS)
|
|
2. Review the full README.md
|
|
3. Verify all prerequisites are met
|
|
4. Test the Nextcloud API directly using curl to isolate issues
|
|
|
|
Happy automating! 🎉
|