# 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`:
```bash
cp .env.example .env
```
3. Edit `.env` with your Nextcloud credentials:
```env
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:
```bash
docker-compose up -d
```
5. The server will be available on `stdio` (standard input/output)
### Option 2: Local Development
1. Install dependencies:
```bash
npm install
```
2. Copy `.env.example` to `.env` and configure your credentials
3. Build the TypeScript code:
```bash
npm run build
```
4. Run the server:
```bash
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:
```json
{
"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:
```json
{
"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
```bash
npm run build
```
### Development Mode
```bash
npm run dev
```
### Watch Mode (auto-rebuild)
```bash
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.
