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:

Variable	Description	Required	Default
NEXTCLOUD_URL	Your Nextcloud instance URL	Yes	-
NEXTCLOUD_USERNAME	Your Nextcloud username	Yes	-
NEXTCLOUD_PASSWORD	App password or user password	Yes	-
PORT	Server port (currently unused for stdio)	No	3000

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:

{
  "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"
      }
    }
  }
}

Or if using Docker:

{
  "mcpServers": {
    "nextcloud-cookbook": {
      "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"
      ]
    }
  }
}

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:

User: "Show me all my recipes"
Claude: [Uses list_recipes tool]

User: "Search for pasta recipes"
Claude: [Uses search_recipes tool with query "pasta"]

User: "Get the details for recipe ID 42"
Claude: [Uses get_recipe tool with id 42]

User: "Import this recipe: https://example.com/recipe"
Claude: [Uses import_recipe tool]

User: "Create a new recipe for chocolate chip cookies"
Claude: [Uses create_recipe tool with recipe data]

Development

Project Structure

nextcloud-cookbook-mcp/
├── src/
│   ├── index.ts              # MCP server implementation
│   └── nextcloud-client.ts   # Nextcloud API client
├── dist/                     # Compiled JavaScript (generated)
├── Dockerfile               # Docker container configuration
├── docker-compose.yml       # Docker Compose setup
├── package.json            # Node.js dependencies
├── tsconfig.json          # TypeScript configuration
└── README.md             # This file

Building

npm run build

Development Mode

npm run dev

Watch Mode (auto-rebuild)

npm run watch

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.