@wh1teee/strapi-mcp
Advanced tools
High-performance MCP server for Strapi CMS with 95% smaller API responses, intelligent field selection, and Strapi v5+ compatibility
An MCP server for Strapi CMS, providing access to content types and entries through the Model Context Protocol.
This MCP server integrates with any Strapi CMS instance to provide:
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_API_TOKEN: Your Strapi API token (Required for authentication).STRAPI_DEV_MODE: Set to "true" to enable development mode features (defaults to false).Example .env file:
STRAPI_URL=http://localhost:1337
STRAPI_API_TOKEN=your_api_token_here
Important:
.env to your .gitignore file to avoid committing credentials"strapi_token" - the server validates and rejects common placeholdersnpm install @wh1teee/@wh1teee/strapi-mcp
For the latest development features:
git clone https://github.com/l33tdawg/@wh1teee/strapi-mcp.git
cd @wh1teee/strapi-mcp
npm install
npm run build
Recommended Method (using Cursor MCP Configuration):
For Cursor users, configure the @wh1teee/strapi-mcp server in your ~/.cursor/mcp.json file:
"@wh1teee/strapi-mcp": {
"command": "npx",
"args": ["@wh1teee/strapi-mcp"],
"env": {
"STRAPI_URL": "http://localhost:1337",
"STRAPI_API_TOKEN": "your_api_token_here"
}
}
If you installed from source, use the direct path instead:
"@wh1teee/strapi-mcp": {
"command": "node",
"args": ["/path/to/@wh1teee/strapi-mcp/build/index.js"],
"env": {
"STRAPI_URL": "http://localhost:1337",
"STRAPI_API_TOKEN": "your_api_token_here"
}
}
Cursor will manage the server lifecycle automatically when @wh1teee/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:
node --env-file=.env build/index.js
Alternative (using environment variables directly):
export STRAPI_URL=http://localhost:1337
export STRAPI_API_TOKEN=your_api_token_here
export STRAPI_DEV_MODE=true # optional
# Run the globally installed package (if installed via npm install -g)
@wh1teee/strapi-mcp
# Or run the local build directly
node build/index.js
get_lightweight_entries: Returns only essential fields, 95% smaller responsesfind_author_by_name: Fast author lookup without full content populateget_schema_fields: Schema-only endpoint without content overheadget_content_preview: Smart preview with essential fields and search| Method | Traditional | Optimized | Improvement |
|---|---|---|---|
| Article listing | 15KB+ | <1KB | 95% smaller |
| Author search | Full populate | Direct lookup | No overhead |
| Schema queries | Mixed data | Pure metadata | Schema only |
| Content preview | Heavy load | Smart fields | 12x faster |
When creating articles (api::articles.articles):
cover (not coverImage) with media ID as integerblocks array with __component: "shared.seo"See Article Creation Guide for complete examples.
get_lightweight_entries: Returns only essential fields, 95% smaller responses than full populatefind_author_by_name: Fast author search without heavy populate overheadget_schema_fields: Schema-only endpoint with enhanced field analysisget_content_preview: Smart preview with configurable limits and searchcreate_entry with detailed article examples and validationget_article_structure_example tool: Get complete examples of correct article structureupdate_media_metadata tool: Update existing media files with alt text and captionsupload_media_from_path and upload_media_from_url now support fileInfo parameterupload_media function (replaced with efficient path/URL methods)publish_entry and unpublish_entry tools: Complete content lifecycle managementlist_components, get_component_schema, create_component, update_componentdelete_content_type tool: Delete existing content types via the Content-Type Builder APIcreate_content_type tool: Allows creating new content types via the Content-Type Builder API.ResourceNotFound and AccessDenied error codesMIT
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:
strapi://content-type/ URIslist_content_types - List all available content types in Strapiget_entries - Get entries for a specific content type with optional filtering, pagination, sorting, and population of relationsget_entry - Get a specific entry by IDcreate_entry - Create a new entry for a content typeupdate_entry - Update an existing entrydelete_entry - Delete an entryupload_media_from_path - Upload a media file from local path with alt text and metadata (efficient, no context token usage)upload_media_from_url - Upload a media file from URL with alt text and metadata (efficient, no context token usage)update_media_metadata - Update alt text, caption, and metadata for existing media files (SEO and accessibility)get_content_type_schema - Get the schema (fields, types, relations) for a specific content type.get_article_structure_example - Get complete examples of correct article structure with field names and validation rules.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.Upload media files with proper alt text, captions, and metadata for better SEO and accessibility:
// Upload from local file path with full metadata (ABSOLUTE PATH REQUIRED)
upload_media_from_path(
'/home/user/photos/image.jpg', // ABSOLUTE path required!
'custom-filename.jpg',
{
alternativeText: 'Beautiful sunset over mountain peaks during golden hour',
caption: 'Landscape photography from our hiking trip to the Alps',
name: 'sunset-alps-golden-hour.jpg'
}
)
// Upload from URL with accessibility metadata
upload_media_from_url(
'https://example.com/product-image.jpg',
null,
{
alternativeText: 'Modern laptop computer on a clean white desk',
caption: 'Product showcase - MacBook Pro 16-inch'
}
)
// Update metadata for existing media files
update_media_metadata('42', {
alternativeText: 'Updated alt text for better SEO and accessibility',
caption: 'New caption that better describes the image content'
})
Why Alt Text Matters:
⚠️ Important: File Path Requirements
/home/user/image.jpg or C:\Users\user\image.jpg./image.jpg, ../image.jpg) or tilde paths (~/image.jpg)The get_entries tool supports advanced query options:
{
"contentType": "api::article.article",
"filters": {
"title": {
"$contains": "hello"
}
},
"pagination": {
"page": 1,
"pageSize": 10
},
"sort": ["title:asc", "createdAt:desc"],
"populate": ["author", "categories"]
}
Resources can be accessed with various URI formats:
strapi://content-type/api::article.article - Get all articlesstrapi://content-type/api::article.article/1 - Get article with ID 1strapi://content-type/api::article.article?filters={"title":{"$contains":"hello"}} - Get filtered articlesThe publish_entry and unpublish_entry tools provide control over the content lifecycle:
{
"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.
Strapi components can be managed with the following tools:
list_components: Get all available componentsget_component_schema: View a specific component's structurecreate_component: Create a new component with specified fieldsupdate_component: Modify an existing componentExample of creating a component:
{
"componentData": {
"displayName": "Security Settings",
"category": "security",
"icon": "shield",
"attributes": {
"enableTwoFactor": {
"type": "boolean",
"default": false
},
"passwordExpiration": {
"type": "integer",
"min": 0
}
}
}
}
Install dependencies:
npm install
Build the server:
npm run build
For development with auto-rebuild:
npm run watch
For detailed step-by-step instructions on how to deploy and test this MCP server, please see the DEPLOYMENT.md file.
Quick setup:
npm run buildOn MacOS: ~/Library/Application Support/Claude/claude_desktop_config.json
On Windows: %APPDATA%/Claude/claude_desktop_config.json
{
"mcpServers": {
"@wh1teee/strapi-mcp": {
"command": "npx",
"args": ["@wh1teee/@wh1teee/strapi-mcp"],
"env": {
"STRAPI_URL": "http://localhost:1337",
"STRAPI_API_TOKEN": "your_api_token_here"
}
}
}
}
If you installed from source, use the direct path:
{
"mcpServers": {
"@wh1teee/strapi-mcp": {
"command": "/path/to/@wh1teee/strapi-mcp/build/index.js",
"env": {
"STRAPI_URL": "http://localhost:1337",
"STRAPI_API_TOKEN": "your_api_token_here"
}
}
}
}
STRAPI_URL (optional): The URL of your Strapi instance (defaults to http://localhost:1337)STRAPI_API_TOKEN: Your Strapi API token (Required for authentication).STRAPI_DEV_MODE (optional): Set to "true" to enable development mode features (defaults to false)The server uses API token-based authentication for secure access to your Strapi instance.
Common Issues and Solutions:
[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.
Cannot connect to Strapi instance: Connection refused. Is Strapi running at http://localhost:1337?
Solution:
npm run develop or yarn developSTRAPI_URL is correctCannot connect to Strapi instance: Authentication failed. Check your API token.
Solution:
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.
As of v0.1.8, the server now clearly distinguishes between:
{"data": [], "meta": {...}}Access forbidden. Your API token may lack necessary permissions.
Solution:
Since MCP servers communicate over stdio, debugging can be challenging. We recommend using the MCP Inspector, which is available as a package script:
npm run inspector
The Inspector will provide a URL to access debugging tools in your browser.
Once the MCP server is configured and running, you can use it with Claude to interact with your Strapi CMS. Here are some examples:
use_mcp_tool(
server_name: "@wh1teee/strapi-mcp",
tool_name: "get_lightweight_entries",
arguments: {
"contentType": "api::articles.articles",
"options": JSON.stringify({
"filters": {"title": {"$containsi": "AI"}},
"pagination": {"pageSize": 10}
})
}
)
use_mcp_tool(
server_name: "@wh1teee/strapi-mcp",
tool_name: "find_author_by_name",
arguments: {
"authorName": "Константин"
}
)
use_mcp_tool(
server_name: "@wh1teee/strapi-mcp",
tool_name: "get_schema_fields",
arguments: {
"contentType": "api::articles.articles"
}
)
use_mcp_tool(
server_name: "@wh1teee/strapi-mcp",
tool_name: "get_content_preview",
arguments: {
"contentType": "api::articles.articles",
"limit": 20,
"search": "neural network"
}
)
use_mcp_tool(
server_name: "@wh1teee/strapi-mcp",
tool_name: "list_content_types",
arguments: {}
)
use_mcp_tool(
server_name: "@wh1teee/strapi-mcp",
tool_name: "get_entries",
arguments: {
"contentType": "api::article.article",
"filters": {
"title": {
"$contains": "hello"
}
},
"pagination": {
"page": 1,
"pageSize": 10
},
"sort": ["title:asc"]
}
)
use_mcp_tool(
server_name: "@wh1teee/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"
}
}
)
use_mcp_tool(
server_name: "@wh1teee/strapi-mcp",
tool_name: "upload_media",
arguments: {
"fileData": "base64-encoded-data-here",
"fileName": "image.jpg",
"fileType": "image/jpeg"
}
)
use_mcp_tool(
server_name: "@wh1teee/strapi-mcp",
tool_name: "connect_relation",
arguments: {
"contentType": "api::article.article",
"id": "1",
"relationField": "authors",
"relatedIds": [2, 3]
}
)
use_mcp_tool(
server_name: "@wh1teee/strapi-mcp",
tool_name: "disconnect_relation",
arguments: {
"contentType": "api::article.article",
"id": "1",
"relationField": "authors",
"relatedIds": [3]
}
)
use_mcp_tool(
server_name: "@wh1teee/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" }
}
}
)
use_mcp_tool(
server_name: "@wh1teee/strapi-mcp-local",
tool_name: "update_content_type",
arguments: {
"contentType": "api::speaker.speaker",
"attributes": {
"isHighlightSpeaker": {
"type": "boolean",
"default": false
},
"newTextField": {
"type": "string"
}
}
}
)
FAQs
High-performance MCP server for Strapi CMS with 95% smaller API responses, intelligent field selection, and Strapi v5+ compatibility
We found that @wh1teee/strapi-mcp demonstrated a healthy version release cadence and project activity because the last version was released less than a year ago. It has 1 open source maintainer collaborating on the project.
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Security News
/Research
Malicious npm package impersonates Nodemailer and drains wallets by hijacking crypto transactions across multiple blockchains.
Security News
This episode explores the hard problem of reachability analysis, from static analysis limits to handling dynamic languages and massive dependency trees.
Security News
/Research
Malicious Nx npm versions stole secrets and wallet info using AI CLI tools; Socket’s AI scanner detected the supply chain attack and flagged the malware.