Nextcloud Cookbook MCP Server

A Model Context Protocol (MCP) server that provides integration with the Nextcloud Cookbook app API. This server allows AI assistants like Claude to interact with your Nextcloud recipes through a standardized interface.

Features

• List and search recipes

• Get detailed recipe information

• Create, update, and delete recipes

• Import recipes from URLs

• Get recipe images

• Manage categories and keywords

• Full Docker support for easy deployment

Prerequisites

• Node.js 18 or higher (for local development)

• Docker and Docker Compose (for containerized deployment)

• Nextcloud instance with Cookbook app installed

• Nextcloud app password (recommended) or user password

Getting a 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 (you won't see it again!)

Installation

Option 1: Docker Deployment (Recommended)

1. Clone or download this repository

2. Copy .env.example to .env:

   cp .env.example .env

3. Edit .env with your Nextcloud credentials:

   NEXTCLOUD_URL=https://your-nextcloud-instance.com NEXTCLOUD_USERNAME=your-username NEXTCLOUD_PASSWORD=your-app-password PORT=3000

4. Build and run with Docker Compose:

   docker-compose up -d

5. The server will be available on stdio (standard input/output)

Option 2: Local Development

1. Install dependencies:

   npm install

2. Copy .env.example to .env and configure your credentials

3. Build the TypeScript code:

   npm run build

4. Run the server:

   npm start

Configuration

Configure the server using environment variables:

Configuring Claude Code

To use this MCP server with Claude Code, add it to your MCP settings:

For stdio transport:

Add to your Claude Code MCP configuration file:

Or if using Docker:

Available Tools

The MCP server provides the following tools:

Recipe Management

• list_recipes - List all recipes in the cookbook

• search_recipes - Search recipes by keyword, tag, or category

• get_recipe - Get detailed information about a specific recipe

• create_recipe - Create a new recipe

• update_recipe - Update an existing recipe

• delete_recipe - Delete a recipe

• import_recipe - Import a recipe from a URL

Images

• get_recipe_image_url - Get the URL for a recipe image (full, thumb, or thumb16)

Organization

• list_categories - List all recipe categories with counts

• list_keywords - List all recipe keywords/tags

• get_recipes_by_keyword - Get recipes tagged with a specific keyword

Example Usage

Once configured with Claude Code, you can interact with your Nextcloud Cookbook using natural language:

Development

Project Structure

Building

Development Mode

Watch Mode (auto-rebuild)

Troubleshooting

Authentication Errors

• Verify your Nextcloud URL is correct (include https://)

• Ensure you're using an app password, not your regular password

• Check that your username is correct (usually lowercase)

Connection Errors

• Verify your Nextcloud instance is accessible

• Check if the Cookbook app is installed and enabled

• Ensure there are no firewall rules blocking access

Docker Issues

• Make sure Docker is running

• Check logs with: docker-compose logs -f

• Rebuild the image: docker-compose build --no-cache

API Reference

For detailed Nextcloud Cookbook API documentation, see: https://nextcloud.github.io/cookbook/dev/api/0.1.2/index.html

License

MIT

Contributing

Contributions are welcome! Please feel free to submit issues or pull requests.