# Strapi MCP Server

AI-powered content management for Strapi CMS via Model Context Protocol.

[![PyPI version](https://img.shields.io/pypi/v/strapi-mcp)](https://pypi.org/project/strapi-mcp/)
[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/licenses/MIT)
[![Python 3.11+](https://img.shields.io/badge/python-3.11+-blue.svg)](https://www.python.org/downloads/)

## Features

Connect any MCP-compatible AI assistant (Claude, Cursor, etc.) to your Strapi CMS. Manage content, media, locales, and more through natural language.

### 20 Tools across 8 categories

| Category | Tools | Description |
|----------|-------|-------------|
| **Schema** (3) | `list_content_types`, `get_content_type_schema`, `get_components` | Discover and inspect content models |
| **Content** (5) | `list_entries`, `get_entry`, `create_entry`, `update_entry`, `delete_entry` | Full CRUD for any content type |
| **Media** (3) | `upload_media`, `list_media`, `delete_media` | Upload, browse, and manage media library |
| **Publish** (3) | `publish_entry`, `unpublish_entry`, `discard_draft` | Control publication lifecycle |
| **i18n** (2) | `list_locales`, `get_localized_entry` | Internationalization support |
| **Search** (2) | `search_entries`, `count_entries` | Full-text search and counting |
| **Bulk** (1) | `bulk_action` | Batch create, update, or delete |
| **System** (1) | `get_strapi_info` | Server info and version detection |

### Additional MCP capabilities

- **3 Prompts**: `manage_content`, `content_migration`, `setup_guide` -- guided workflows for common tasks
- **1 Resource**: `strapi://help` -- comprehensive usage guide with examples

## Quick Start

1. **Install** the server:
   ```bash
   pip install strapi-mcp
   ```

2. **Configure** your Strapi connection:
   ```bash
   export STRAPI_BASE_URL="http://localhost:1337"
   export STRAPI_API_TOKEN="your-strapi-api-token"
   ```

3. **Connect** from your MCP client (see [Client Configuration](#client-configuration) below).

## Installation

### Using pip

```bash
pip install strapi-mcp
```

### Using uvx (no install required)

```bash
uvx strapi-mcp
```

### From source

```bash
git clone https://github.com/alexzimmermann/strapi-mcp.git
cd strapi-mcp
pip install -e .
```

## Configuration

All settings are configured via environment variables with the `STRAPI_` prefix:

| Variable | Default | Description |
|----------|---------|-------------|
| `STRAPI_BASE_URL` | `http://localhost:1337` | URL of your Strapi instance |
| `STRAPI_API_TOKEN` | *(empty)* | API token for authentication. Create in Strapi Admin > Settings > API Tokens. |
| `STRAPI_API_VERSION` | `auto` | Strapi version: `auto`, `v4`, or `v5` |
| `STRAPI_TIMEOUT` | `30` | HTTP request timeout in seconds |
| `STRAPI_MAX_PAGE_SIZE` | `100` | Maximum entries per page (1-100) |

You can also place these in a `.env` file in your working directory.

### Creating a Strapi API Token

1. Open your Strapi Admin panel (e.g., `http://localhost:1337/admin`)
2. Navigate to **Settings > API Tokens**
3. Click **Create new API Token**
4. Set **Token type** to **Full Access** (or customize permissions)
5. Copy the generated token and set it as `STRAPI_API_TOKEN`

## Client Configuration

### Claude Desktop

Add to your Claude Desktop config file (`claude_desktop_config.json`):

```json
{
  "mcpServers": {
    "strapi": {
      "command": "uvx",
      "args": ["strapi-mcp"],
      "env": {
        "STRAPI_BASE_URL": "http://localhost:1337",
        "STRAPI_API_TOKEN": "your-strapi-api-token"
      }
    }
  }
}
```

### Cursor

Add to your Cursor MCP config:

```json
{
  "mcpServers": {
    "strapi": {
      "command": "uvx",
      "args": ["strapi-mcp"],
      "env": {
        "STRAPI_BASE_URL": "http://localhost:1337",
        "STRAPI_API_TOKEN": "your-strapi-api-token"
      }
    }
  }
}
```

### Smithery

This server is available on [Smithery](https://smithery.ai). Install directly from the Smithery registry or configure manually using the `smithery.yaml` included in this repository.

## Available Tools

| Tool | Description |
|------|-------------|
| `list_content_types` | List all available content types in the Strapi instance |
| `get_content_type_schema` | Get the full field schema for a specific content type |
| `get_components` | List all reusable components and their schemas |
| `list_entries` | List entries with filtering, sorting, pagination, and population |
| `get_entry` | Get a single entry by ID (or documentId in v5) |
| `create_entry` | Create a new content entry with field data |
| `update_entry` | Update an existing entry by ID |
| `delete_entry` | Delete an entry by ID |
| `upload_media` | Upload a file to the media library (URL or base64) |
| `list_media` | Browse the media library with pagination |
| `delete_media` | Delete a file from the media library |
| `publish_entry` | Publish a draft entry to make it publicly available |
| `unpublish_entry` | Revert a published entry to draft status |
| `discard_draft` | Discard unsaved draft changes (Strapi v5 only) |
| `list_locales` | List all configured locales for i18n |
| `get_localized_entry` | Get an entry in a specific locale |
| `search_entries` | Full-text search across entries of a content type |
| `count_entries` | Count entries matching optional filter criteria |
| `bulk_action` | Perform bulk create, update, or delete operations |
| `get_strapi_info` | Get Strapi server info, version, and connection status |

## Strapi Version Support

This server supports both **Strapi v4** and **Strapi v5** with automatic version detection.

### Auto-detection

When `STRAPI_API_VERSION` is set to `auto` (the default), the server detects your Strapi version at startup by:

1. Fetching a content type entry and inspecting its response format
2. Checking the admin information endpoint for a version string
3. Defaulting to v5 if detection is inconclusive

### Key differences handled automatically

| Feature | Strapi v4 | Strapi v5 |
|---------|-----------|-----------|
| Entry format | Nested `data.attributes` | Flat with `documentId` |
| Entry identifier | Numeric `id` | String `documentId` |
| Publication status | `publicationState=live\|preview` | `status=published\|draft` |
| Draft discard | Not available | `discard_draft` tool |

You can force a specific version by setting `STRAPI_API_VERSION=v4` or `STRAPI_API_VERSION=v5`.

## Development

### Setup

```bash
git clone https://github.com/alexzimmermann/strapi-mcp.git
cd strapi-mcp
python -m venv .venv
source .venv/bin/activate  # or .venv\Scripts\activate on Windows
pip install -e ".[dev]"
```

### Running tests

```bash
pytest
```

### Running with coverage

```bash
pytest --cov=strapi_mcp --cov-report=term-missing
```

### Code style

```bash
ruff check .
ruff format .
```

## License

MIT License. See [LICENSE](LICENSE) for details.