Content
# Strapi MCP
An MCP server for Strapi CMS, providing access to content types and entries through the Model Context Protocol.
## Overview
This MCP server integrates with any Strapi CMS instance to provide:
- Access to Strapi content types as resources
- Tools to create and update content types in Strapi
- Tools to manage content entries (create, read, update, delete)
- Support for Strapi in development mode
- **Robust error handling** with clear diagnostics and troubleshooting guidance
- **Configuration validation** to prevent common setup issues
## Setup
### Environment Variables
It's recommended to use a `.env` file in the project root to store your credentials.
- `STRAPI_URL`: The URL of your Strapi instance (default: `http://localhost:1337`)
- `STRAPI_ADMIN_EMAIL`: The email address for a Strapi admin user (Recommended for full functionality, especially schema access).
- `STRAPI_ADMIN_PASSWORD`: The password for the Strapi admin user (Recommended).
- `STRAPI_API_TOKEN`: (Optional Fallback) An API token. Can be used if admin credentials are not provided, but may have limited permissions.
- `STRAPI_DEV_MODE`: Set to `"true"` to enable development mode features (defaults to `false`).
**Example `.env` file:**
```dotenv
STRAPI_URL=http://localhost:1337
STRAPI_ADMIN_EMAIL=your_admin_email@example.com
STRAPI_ADMIN_PASSWORD=your_admin_password
# STRAPI_API_TOKEN=your_api_token_here # Optional
```
**Important:**
- Add `.env` to your `.gitignore` file to avoid committing credentials
- Avoid placeholder values like `"strapi_token"` - the server validates and rejects common placeholders
### Installation
#### Install from npm (Recommended)
```bash
npm install strapi-mcp
```
#### Install from source (Development)
For the latest development features:
```bash
git clone https://github.com/l33tdawg/strapi-mcp.git
cd strapi-mcp
npm install
npm run build
```
### Running
**Recommended Method (using Cursor MCP Configuration):**
For Cursor users, configure the strapi-mcp server in your `~/.cursor/mcp.json` file:
```json
"strapi-mcp": {
"command": "npx",
"args": ["strapi-mcp"],
"env": {
"STRAPI_URL": "http://localhost:1337",
"STRAPI_ADMIN_EMAIL": "your_admin_email@example.com",
"STRAPI_ADMIN_PASSWORD": "your_admin_password"
}
}
```
If you installed from source, use the direct path instead:
```json
"strapi-mcp": {
"command": "node",
"args": ["/path/to/strapi-mcp/build/index.js"],
"env": {
"STRAPI_URL": "http://localhost:1337",
"STRAPI_ADMIN_EMAIL": "your_admin_email@example.com",
"STRAPI_ADMIN_PASSWORD": "your_admin_password"
}
}
```
Cursor will manage the server lifecycle automatically when strapi-mcp tools are used.
**Alternative Method (using `.env` file):**
Make sure you have built the project (`npm run build`). Then run the server using Node.js v20.6.0+ with the `--env-file` flag:
```bash
node --env-file=.env build/index.js
```
**Alternative (using environment variables directly):**
```bash
export STRAPI_URL=http://localhost:1337
export STRAPI_ADMIN_EMAIL=your_admin_email@example.com
export STRAPI_ADMIN_PASSWORD=your_admin_password
# export STRAPI_API_TOKEN=your-api-token # Optional fallback
export STRAPI_DEV_MODE=true # optional
# Run the globally installed package (if installed via npm install -g)
strapi-mcp
# Or run the local build directly
node build/index.js
```
## Features
- List and read content types
- Get, create, update, and delete entries
- Upload media files
- Connect and disconnect relations
- Get content type schemas
## Changelog
### 0.2.3 - 2025-07-25
- **CRITICAL FIX:** Fixed timeout issue in relation tools - connect_relation and disconnect_relation now properly handle validation errors instead of timing out
- **IMPROVED ERROR HANDLING:** All validation errors now return proper error messages instead of causing tool timeouts
### 0.2.2 - 2025-07-25
- **ENHANCED RELATION TOOLS:** Improved error handling for `connect_relation` and `disconnect_relation` with detailed validation and troubleshooting messages
- **FIXED CREATE_COMPONENT:** Fixed parameter validation bug - now properly validates individual parameters instead of single object
- **BETTER ERROR DIAGNOSTICS:** Added specific error messages for invalid relation fields, non-existent entries, and malformed IDs
- All 20 tools now working at 100% with robust error handling and validation
### 0.2.0 - 2025-07-25
- **CRITICAL BUG FIX:** Fixed validateStrapiConnection causing "undefined response status" error
- **RESOLVED MCP CONNECTION ISSUE:** Fixed the "green light but doesn't work" problem with AI tools
- **IMPROVED ERROR HANDLING:** Better connection validation logic with proper admin auth handling
- Users should update to this version if experiencing MCP connection issues with AI tools
### 0.1.9 - 2025-07-02
- **CONTEXT WINDOW OVERFLOW FIX:** Added size limits and response filtering to prevent base64 files from overwhelming context window
- **NEW TOOL:** Added `upload_media_from_path` - Upload files from local file paths (max 10MB) to avoid base64 context issues
- **ENHANCED UPLOAD_MEDIA:** Added 1MB base64 size limit (~750KB file) with clear error messages about context overflow
- **IMPROVED LOGGING:** Truncated base64 data in logs to prevent log spam and context overflow
- **RESPONSE FILTERING:** Automatically filters large base64 strings from API responses to prevent echo overflow
### 0.1.8 - 2025-06-12
- **MAJOR BUG FIX:** Replaced silent failures with descriptive error messages when content types or entries cannot be fetched
- **Added Configuration Validation:** Detects placeholder API tokens and exits with helpful error messages
- **Added Connection Validation:** Tests Strapi connectivity before attempting operations with specific error diagnostics
- **Enhanced Error Handling:** Comprehensive error diagnostics that distinguish between legitimate empty collections vs actual errors
- **Improved Troubleshooting:** All error messages include specific steps to resolve common configuration issues
### 0.1.7 - 2025-05-17
- **Added `publish_entry` and `unpublish_entry` tools:** Complete content lifecycle management
- **Added Component Management:** `list_components`, `get_component_schema`, `create_component`, `update_component`
- **Added `delete_content_type` tool:** Delete existing content types via the Content-Type Builder API
- **Enhanced Admin Authentication:** Better error handling and token management for all API operations
### 0.1.6
- **Added `create_content_type` tool:** Allows creating new content types via the Content-Type Builder API (requires admin credentials).
- **Prioritized Admin Credentials:** Updated logic to prefer admin email/password for fetching content types and schemas, improving reliability.
- **Updated Documentation:** Clarified authentication methods and recommended running procedures.
### 0.1.5
- Improved content type discovery with multiple fallback methods
- Added more robust error handling and logging
- Enhanced schema inference for content types
### 0.1.4
- Improved error handling with more specific error codes
- Added `ResourceNotFound` and `AccessDenied` error codes
- Better error messages for common API errors
### 0.1.3
- Initial public release
## License
MIT
# strapi-mcp MCP Server
An MCP server for your Strapi CMS
This is a TypeScript-based MCP server that integrates with Strapi CMS. It provides access to Strapi content types and entries through the MCP protocol, allowing you to:
- Access Strapi content types as resources
- Create, read, update, and delete content entries
- Manage your Strapi content through MCP tools
## Features
### Resources
- List and access content types via `strapi://content-type/` URIs
- Each content type exposes its entries as JSON
- Application/JSON mime type for structured content access
### Tools
- `list_content_types` - List all available content types in Strapi
- `get_entries` - Get entries for a specific content type with optional filtering, pagination, sorting, and population of relations
- `get_entry` - Get a specific entry by ID
- `create_entry` - Create a new entry for a content type
- `update_entry` - Update an existing entry
- `delete_entry` - Delete an entry
- `upload_media` - Upload a media file to Strapi (max ~750KB file due to base64 context limits)
- `upload_media_from_path` - Upload a media file from local file path (max 10MB, avoids context overflow)
- `get_content_type_schema` - Get the schema (fields, types, relations) for a specific content type.
- `connect_relation` - Connect related entries to an entry's relation field.
- `disconnect_relation` - Disconnect related entries from an entry's relation field.
- `create_content_type` - Create a new content type using the Content-Type Builder API (Requires Admin privileges).
- `publish_entry` - Publish a specific entry.
- `unpublish_entry` - Unpublish a specific entry.
- `list_components` - List all available components in Strapi.
- `get_component_schema` - Get the schema for a specific component.
- `create_component` - Create a new component.
- `update_component` - Update an existing component.
### Advanced Features
#### Filtering, Pagination, and Sorting
The `get_entries` tool supports advanced query options:
```json
{
"contentType": "api::article.article",
"filters": {
"title": {
"$contains": "hello"
}
},
"pagination": {
"page": 1,
"pageSize": 10
},
"sort": ["title:asc", "createdAt:desc"],
"populate": ["author", "categories"]
}
```
#### Resource URIs
Resources can be accessed with various URI formats:
- `strapi://content-type/api::article.article` - Get all articles
- `strapi://content-type/api::article.article/1` - Get article with ID 1
- `strapi://content-type/api::article.article?filters={"title":{"$contains":"hello"}}` - Get filtered articles
### Publishing and Unpublishing Content
The `publish_entry` and `unpublish_entry` tools provide control over the content lifecycle:
```json
{
"contentType": "api::article.article",
"id": "1"
}
```
These tools utilize the admin API paths for publishing/unpublishing actions, with a fallback to directly updating the `publishedAt` field if admin permissions are not available.
### Component Management
Strapi components can be managed with the following tools:
- `list_components`: Get all available components
- `get_component_schema`: View a specific component's structure
- `create_component`: Create a new component with specified fields
- `update_component`: Modify an existing component
Example of creating a component:
```json
{
"componentData": {
"displayName": "Security Settings",
"category": "security",
"icon": "shield",
"attributes": {
"enableTwoFactor": {
"type": "boolean",
"default": false
},
"passwordExpiration": {
"type": "integer",
"min": 0
}
}
}
}
```
## Development
Install dependencies:
```bash
npm install
```
Build the server:
```bash
npm run build
```
For development with auto-rebuild:
```bash
npm run watch
```
## Installation
For detailed step-by-step instructions on how to deploy and test this MCP server, please see the [DEPLOYMENT.md](./DEPLOYMENT.md) file.
Quick setup:
1. Build the server: `npm run build`
2. Configure your Strapi instance and get an API token
3. Add the server config to Claude Desktop:
On MacOS: `~/Library/Application Support/Claude/claude_desktop_config.json`
On Windows: `%APPDATA%/Claude/claude_desktop_config.json`
```json
{
"mcpServers": {
"strapi-mcp": {
"command": "npx",
"args": ["strapi-mcp"],
"env": {
"STRAPI_URL": "http://localhost:1337",
"STRAPI_ADMIN_EMAIL": "your_admin_email@example.com",
"STRAPI_ADMIN_PASSWORD": "your_admin_password"
}
}
}
}
```
If you installed from source, use the direct path:
```json
{
"mcpServers": {
"strapi-mcp": {
"command": "/path/to/strapi-mcp/build/index.js",
"env": {
"STRAPI_URL": "http://localhost:1337",
"STRAPI_ADMIN_EMAIL": "your_admin_email@example.com",
"STRAPI_ADMIN_PASSWORD": "your_admin_password"
}
}
}
}
```
### Environment Variables
- `STRAPI_URL` (optional): The URL of your Strapi instance (defaults to http://localhost:1337)
- `STRAPI_ADMIN_EMAIL` & `STRAPI_ADMIN_PASSWORD` (Recommended): Credentials for a Strapi admin user. Required for full functionality like fetching content type schemas.
- `STRAPI_API_TOKEN` (Optional Fallback): Your Strapi API token. Can be used if admin credentials are not provided, but functionality might be limited based on token permissions.
- `STRAPI_DEV_MODE` (optional): Set to "true" to enable development mode features (defaults to false)
### Authentication Priority
The server prioritizes authentication methods in this order:
1. Admin Email & Password (`STRAPI_ADMIN_EMAIL`, `STRAPI_ADMIN_PASSWORD`)
2. API Token (`STRAPI_API_TOKEN`)
It's strongly recommended to use Admin Credentials for the best results.
### Getting Strapi Credentials
- **Admin Credentials:** Use the email and password of an existing Super Admin or create a dedicated admin user in your Strapi admin panel (Settings > Administration Panel > Users).
- **API Token:** (Optional Fallback)
1. Log in to your Strapi admin panel
2. Go to Settings > API Tokens
3. Click "Create new API Token"
4. Set a name, description, and token type (preferably "Full access")
5. Copy the generated token and use it in your MCP server configuration
### Troubleshooting
**Common Issues and Solutions:**
#### 1. **Placeholder API Token Error**
```
[Error] STRAPI_API_TOKEN appears to be a placeholder value...
```
**Solution:** Replace `"strapi_token"` or `"your-api-token-here"` with a real API token from your Strapi admin panel.
#### 2. **Connection Refused Error**
```
Cannot connect to Strapi instance: Connection refused. Is Strapi running at http://localhost:1337?
```
**Solution:**
- Ensure Strapi is running: `npm run develop` or `yarn develop`
- Check if the URL in `STRAPI_URL` is correct
- Verify your database (MySQL/PostgreSQL) is running
#### 3. **Authentication Failed**
```
Cannot connect to Strapi instance: Authentication failed. Check your API token or admin credentials.
```
**Solution:**
- Verify your API token has proper permissions (preferably "Full access")
- Check admin email/password are correct
- Ensure the admin user exists and is active
#### 4. **Context Window Overflow with File Uploads**
```
Error: Context window overflow due to large base64 strings
```
**Problem:** Base64 encoded files can be extremely large (even small images can be 50-100KB of text), causing context window overflow.
**Solutions:**
- **Use `upload_media_from_path` instead of `upload_media`** for files larger than ~500KB
- **Reduce file sizes** before uploading (compress images, reduce resolution)
- **Use smaller files** - the `upload_media` tool has a 1MB base64 limit (~750KB file)
#### 5. **Fake Content Types** (`api::data.data`, `api::error.error`)
This issue has been **fixed in v0.1.8**. If you still see these, you may be using an older version.
#### 6. **Empty Results vs Errors**
As of v0.1.8, the server now clearly distinguishes between:
- **Empty collections** (content type exists but has no entries) → Returns `{"data": [], "meta": {...}}`
- **Actual errors** (content type doesn't exist, auth failed, etc.) → Throws descriptive error with troubleshooting steps
#### 7. **Permission Errors**
```
Access forbidden. Your API token may lack necessary permissions.
```
**Solution:**
- Use admin credentials instead of API token for full functionality
- If using API token, ensure it has "Full access" permissions
- Check that the content type allows public access if using limited API token
### Debugging
Since MCP servers communicate over stdio, debugging can be challenging. We recommend using the [MCP Inspector](https://github.com/modelcontextprotocol/inspector), which is available as a package script:
```bash
npm run inspector
```
The Inspector will provide a URL to access debugging tools in your browser.
## Usage Examples
Once the MCP server is configured and running, you can use it with Claude to interact with your Strapi CMS. Here are some examples:
### Listing Content Types
```
use_mcp_tool(
server_name: "strapi-mcp",
tool_name: "list_content_types",
arguments: {}
)
```
### Getting Entries
```
use_mcp_tool(
server_name: "strapi-mcp",
tool_name: "get_entries",
arguments: {
"contentType": "api::article.article",
"filters": {
"title": {
"$contains": "hello"
}
},
"pagination": {
"page": 1,
"pageSize": 10
},
"sort": ["title:asc"]
}
)
```
### Creating an Entry
```
use_mcp_tool(
server_name: "strapi-mcp",
tool_name: "create_entry",
arguments: {
"contentType": "api::article.article",
"data": {
"title": "My New Article",
"content": "This is the content of my article.",
"publishedAt": "2023-01-01T00:00:00.000Z"
}
}
)
```
### Uploading Media
**Method 1: Base64 upload (small files only)**
```
use_mcp_tool(
server_name: "strapi-mcp",
tool_name: "upload_media",
arguments: {
"fileData": "base64-encoded-data-here",
"fileName": "image.jpg",
"fileType": "image/jpeg"
}
)
```
**Method 2: File path upload (recommended for larger files)**
```
use_mcp_tool(
server_name: "strapi-mcp",
tool_name: "upload_media_from_path",
arguments: {
"filePath": "/path/to/your/image.jpg"
}
)
```
### Connecting Relations
```
use_mcp_tool(
server_name: "strapi-mcp",
tool_name: "connect_relation",
arguments: {
"contentType": "api::article.article",
"id": "1",
"relationField": "authors",
"relatedIds": [2, 3]
}
)
```
### Disconnecting Relations
```
use_mcp_tool(
server_name: "strapi-mcp",
tool_name: "disconnect_relation",
arguments: {
"contentType": "api::article.article",
"id": "1",
"relationField": "authors",
"relatedIds": [3]
}
)
```
### Creating a Content Type
```
use_mcp_tool(
server_name: "strapi-mcp-local",
tool_name: "create_content_type",
arguments: {
"displayName": "My New Product",
"singularName": "product",
"pluralName": "products",
"kind": "collectionType",
"description": "Represents products in the store",
"draftAndPublish": true,
"attributes": {
"name": { "type": "string", "required": true },
"description": { "type": "text" },
"price": { "type": "decimal", "required": true },
"stock": { "type": "integer" }
}
}
)
```
### Updating a Content Type
```
use_mcp_tool(
server_name: "strapi-mcp-local",
tool_name: "update_content_type",
arguments: {
"contentType": "api::speaker.speaker",
"attributes": {
"isHighlightSpeaker": {
"type": "boolean",
"default": false
},
"newTextField": {
"type": "string"
}
}
}
)
```
### Accessing Resources
```
