nextcloud-mcp/QUICKSTART.md

# 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
- Use `list_calendars` to discover exact calendar names/hrefs

### 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. Use `list_calendars`, then call `get_calendar_events` with `calendar` or `calendars` when you want specific calendars
2. Add more tools as needed for your workflow
3. Check out the full README.md for advanced features

## 🔍 CalDAV Quick Debug (curl)

List calendars:
```bash
curl -u "$NEXTCLOUD_USERNAME:$NEXTCLOUD_PASSWORD" \
  -X PROPFIND \
  -H "Depth: 1" \
  -H "Accept: application/xml" \
  -H "Content-Type: application/xml; charset=utf-8" \
  --data '<?xml version="1.0" encoding="UTF-8"?>
<d:propfind xmlns:d="DAV:" xmlns:c="urn:ietf:params:xml:ns:caldav">
  <d:prop>
    <d:displayname />
    <d:resourcetype />
    <c:supported-calendar-component-set />
  </d:prop>
</d:propfind>' \
  "$NEXTCLOUD_URL/remote.php/dav/calendars/$NEXTCLOUD_USERNAME/"
```

Query events:
```bash
curl -u "$NEXTCLOUD_USERNAME:$NEXTCLOUD_PASSWORD" \
  -X REPORT \
  -H "Depth: 1" \
  -H "Accept: application/xml" \
  -H "Content-Type: application/xml; charset=utf-8" \
  --data '<?xml version="1.0" encoding="UTF-8"?>
<c:calendar-query xmlns:c="urn:ietf:params:xml:ns:caldav" xmlns:d="DAV:">
  <d:prop>
    <d:getetag />
    <c:calendar-data />
  </d:prop>
  <c:filter>
    <c:comp-filter name="VCALENDAR">
      <c:comp-filter name="VEVENT">
        <c:time-range start="20260201T000000Z" end="20260301T000000Z"/>
      </c:comp-filter>
    </c:comp-filter>
  </c:filter>
</c:calendar-query>' \
  "$NEXTCLOUD_URL/remote.php/dav/calendars/$NEXTCLOUD_USERNAME/personal/"
```

## 📚 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! 🎉