Nextcloud Cookbook

You deploy the Nextcloud Cookbook MCP Server to enable an AI assistant to interact with your Nextcloud Cookbook app. It exposes common recipe operations through a standardized MCP interface, letting you list, search, read, create, update, delete, and import recipes, along with managing images, categories, and keywords.

How to use

You connect an MCP client to the server using either a local (stdio) setup or a Docker-based runtime. Once connected, you can ask the assistant to list your recipes, search by keywords or categories, view detailed recipe information, and perform create, update, or delete operations. You can also import recipes from URLs and retrieve recipe images. The server is designed to work with Claude Code or other MCP clients that support stdio transport, and it can run as a Docker container or as a local Node.js process.

How to install

Prerequisites you need before installation are listed here. Ensure you have a Nextcloud instance with the Cookbook app installed, along with a user password or an app password for authentication.

Option 1: Docker Deployment (Recommended)

1. Prepare the environment by copying the example environment configuration to a real one.

2. Create the environment file with your credentials.

3. Start the container stack with Docker Compose.

4. Access the MCP server through standard input/output with the configured runtime.

Example commands you will run during setup, shown as concrete steps you can follow:

cp .env.example .env

# Edit .env to include your Nextcloud details
NEXTCLOUD_URL=https://your-nextcloud-instance.com
NEXTCLOUD_USERNAME=your-username
NEXTCLOUD_PASSWORD=your-app-password
PORT=3000

docker-compose up -d

Option 2: Local Development

1. Install dependencies for the project.

2. Copy the environment example and configure credentials.

3. Build the TypeScript code and start the server locally.

Concrete commands you can run locally to develop and test the MCP server are shown here.

npm install

cp .env.example .env
# Configure environment variables in .env

npm run build

npm start

Configuration

Configure the server using environment variables. The server requires your Nextcloud instance URL, a username, and an app/password for authentication. The port setting is optional and currently not used for stdio transport.

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

Notes on Claude Code integration and runtime options

You can configure Claude Code to run the Nextcloud Cookbook MCP Server either natively on your machine or inside Docker. The examples show both approaches so you can choose what best fits your workflow.

Local stdio configuration uses a Node.js entry point in your project.

Docker configuration runs the MCP server container and passes credentials via environment variables.

# Local stdio (example)
{
  "mcpServers": {
    "nextcloud_cookbook": {
      "command": "node",
      "args": ["/path/to/nextcloud-cookbook-mcp/dist/index.js"],
      "env": {
        "NEXTCLOUD_URL": "https://your-nextcloud-instance.com",
        "NEXTCLOUD_USERNAME": "your-username",
        "NEXTCLOUD_PASSWORD": "your-app-password"
      }
    }
  }
}

Docker runtime example uses the MCP image directly.

# Docker stdio (example)
{
  "mcpServers": {
    "nextcloud_cookbook_docker": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "-e", "NEXTCLOUD_URL=https://your-nextcloud-instance.com",
        "-e", "NEXTCLOUD_USERNAME=your-username",
        "-e", "NEXTCLOUD_PASSWORD=your-app-password",
        "nextcloud-cookbook-mcp"
      ]
    }
  }
}

Troubleshooting

Authentication errors commonly indicate an incorrect Nextcloud URL, an invalid app password, or a wrong username. Ensure you can access the Nextcloud instance from the MCP server host and that the Cookbook app is installed and enabled.

Connection issues may arise if network access is blocked by a firewall or if the Cookbook app is not available. Verify accessibility of the Nextcloud instance and credentials.

Docker-related problems can be diagnosed with container logs and by rebuilding the image if necessary.

Common commands to diagnose and recover: check Docker daemon status, view container logs, and re-run builds as needed.

Available tools

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.

get_recipe_image_url

Get the URL for a recipe image (full, thumb, or thumb16).

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.