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:

cp .env.example .env

Edit .env with your details:

NEXTCLOUD_URL=https://your-nextcloud.com
NEXTCLOUD_USERNAME=your-username
NEXTCLOUD_PASSWORD=paste-your-app-password-here

Step 3: Build and Test

# 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):

{
  "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! 🎉