Strapi Content Manager MCP Adapter

This package establishes an MCP endpoint specifically designed to interface with a running Strapi headless CMS backend. It exposes Strapi's content repository and configuration schema as managed resources within the MCP environment, enabling programmatic control over data lifecycle.

Core Functionality

This adapter provides full CRUD operations for content entries and structure modification capabilities:

• Resource Access: Treats Strapi content types as discoverable resources.
• Data Manipulation: Enables atomic creation, retrieval, modification, and deletion of individual records.
• Schema Introspection: Allows querying the structure (fields, relations) of content types and components.
• Asset Handling: Supports file uploads, mitigating context window limits via path-based transfers.
• Lifecycle Control: Tools for publishing and retiring content items.
• Development Mode Features: Specific hooks for environments where schema changes are frequent.

Configuration and Deployment

Operation requires connectivity to a Strapi instance. Configuration is primarily driven by environment variables, prioritizing admin credentials for full feature access:

Required Environment Variables

Configuration settings must define the target CMS location and credentials. Sensitive information should be stored securely (e.g., in a .env file, excluded via .gitignore):

Variable	Description	Default	Notes
STRAPI_URL	Base URI of the Strapi server.	http://localhost:1337	Essential for connection.
STRAPI_ADMIN_EMAIL	Administrator email address.	None	Highly recommended for schema access.
STRAPI_ADMIN_PASSWORD	Corresponding administrator password.	None	Highly recommended.
STRAPI_API_TOKEN	Fallback token for restricted access.	None	Used if admin credentials are absent.
STRAPI_DEV_MODE	Flag to enable development-focused features.	false	Set to "true" for active development environments.

Example Environment Setup (.env file):

STRAPI_URL=http://my-remote-strapi.com:8080
STRAPI_ADMIN_EMAIL=super_user@corp.com
STRAPI_ADMIN_PASSWORD=SecureSecret123

Installation Procedures

A. Standard Package Installation (Production/Standard Use):

npm install strapi-mcp-adapter

B. Source Installation (For Development/Modification):

git clone https://github.com/l33tdawg/strapi-mcp.git
cd strapi-mcp
npm install
npm run build

Execution Methods

1. Cursor/IDE Integration (Recommended)

Configure the launcher within your IDE's MCP settings (e.g., ~/.cursor/mcp.json) to manage the server lifecycle automatically:

"strapi-mcp-adapter": {
  "command": "npx",
  "args": ["strapi-mcp-adapter"], 
  "env": {
    "STRAPI_URL": "http://localhost:1337",
    "STRAPI_ADMIN_EMAIL": "admin@example.com",
    "STRAPI_ADMIN_PASSWORD": "admin_pass"
  }
}

If running from a local build directory, adjust command to node and point args to the compiled entry point.

2. Direct Node Execution

Ensure Node.js version 20.6.0 or newer is installed. Execute using the environment file:

node --env-file=.env build/index.js

Alternatively, export variables directly to the shell:

export STRAPI_URL=http://localhost:1337
# ... set other variables ...
strapi-mcp-adapter 
# OR 
node build/index.js

Available Toolset & Resources

The adapter exposes resources under the strapi://content-type/ URI scheme. Tools interact with these resources:

Content & Schema Operations

Tool Name	Functionality
list_content_types	Enumerates all available content schemas.
get_content_type_schema	Retrieves the detailed attribute structure for a specified type.
get_entries	Fetches collections, supporting advanced Strapi query parameters (filters, pagination, sorting, population).
get_entry	Retrieves a single record by its identifier.
create_entry	Inserts a new data entry.
update_entry	Modifies an existing record.
delete_entry	Removes a record permanently.

Lifecycle & Relation Management

Tool Name	Functionality
publish_entry	Sets an entry to the published state.
unpublish_entry	Revokes publication status for an entry.
connect_relation	Links specified related entries to a source record's field.
disconnect_relation	Breaks established links in a relation field.

Asset Uploads

Tool Name	Functionality
upload_media	Uploads file data provided as a base64 string (limited size to prevent context bloat).
upload_media_from_path	Uploads a file directly from the local filesystem path (supports larger files up to 10MB).

Component Management (Schema Builder API)

Tool Name	Functionality
list_components	Lists all registered component definitions.
get_component_schema	Dumps the structural definition of a component.
create_component	Programmatically defines a new component structure.
update_component	Modifies an existing component definition.
delete_content_type	Removes an entire content type structure.

Evolution Log (Selected Updates)

Version 0.2.3 (2025-07-25) * CRITICAL REPAIR: Resolved connection timeouts occurring during relation manipulation (connect_relation, disconnect_relation) by ensuring validation failures are returned as explicit errors, not stalls. * DIAGNOSTICS: Enhanced error mapping: all input validation failures now yield clean diagnostic messages instead of causing tool execution timeouts.

Version 0.2.2 (2025-07-25) * RELATION ENHANCEMENT: Improved robustness for relation linking/unlinking functions, including better feedback on schema mismatches. * BUG FIX: Rectified a flaw in create_component where parameter validation was incorrectly collapsing arguments into a single object check. * CLARITY: Introduced specific error codes for known issues like invalid relation fields or missing resource IDs.

Version 0.1.9 (2025-07-02) * CONTEXT MANAGEMENT: Implemented strict size limitations and response filtering for base64 data transfer to safeguard the MCP context window capacity. * NEW TOOL: Introduced upload_media_from_path to enable handling files exceeding the base64 transfer limit via direct path reference. * LOGGING SANITY: Truncated base64 payloads within internal logging streams to prevent excessive log volume.

Version 0.1.8 (2025-06-12) * ERROR REPORTING: Replaced ambiguous silent failures during data fetching with descriptive error outputs. * SETUP VALIDATION: Added pre-flight checks to flag usage of default placeholder values for configuration secrets. * CONNECTIVITY TEST: Implemented immediate validation of the Strapi connection upon startup, providing detailed diagnostics if authentication or reachability fails.

Integration Details

Query Structure Example (get_entries)

Advanced retrieval utilizes Strapi's flexible query structure:

{
  "contentType": "api::blog-post.blog-post",
  "filters": {
    "status": "published",
    "author.name": {"$eq": "Jane Doe"}
  },
  "pagination": {"limit": 25},
  "sort": ["updatedAt:desc"]
}

Resource Addressing

Resources are addressable via URI structure: * strapi://content-type/api::user.user (List all users) * strapi://content-type/api::user.user/5 (Retrieve user ID 5)

Development Workflow

To contribute or inspect the server's internal state, use the provided debugging scripts:

1. Build: npm run build
2. Watch Mode (Live Reload): npm run watch
3. Debugging: Utilize the bundled MCP Inspector utility: bash npm run inspector (This launches a browser interface for inspecting inter-process communication.)

License

Distributed under the terms of the MIT License.

Example Usage Scenarios (MCP Tool Calls)

Once the server is operational, utilize the use_mcp_tool function with the established server name (strapi-mcp-adapter):

1. Retrieving a Published Article List:

use_mcp_tool(
  server_name: "strapi-mcp-adapter",
  tool_name: "get_entries",
  arguments: {
    "contentType": "api::article.article",
    "filters": { "publishedAt": { "$notNull": true } }
  }
)

2. Defining a New Collection Type:

use_mcp_tool(
  server_name: "strapi-mcp-adapter",
  tool_name: "create_content_type",
  arguments: {
    "displayName": "TeamMember",
    "singularName": "teamMember",
    "kind": "collectionType",
    "attributes": {
      "fullName": { "type": "string", "required": true },
      "role": { "type": "enumeration", "enum": ["Developer", "Designer"] }
    }
  }
)

3. Linking Two Records:

use_mcp_tool(
  server_name: "strapi-mcp-adapter",
  tool_name: "connect_relation",
  arguments: {
    "contentType": "api::project.project",
    "id": "10",
    "relationField": "primaryTeam",
    "relatedIds": [42, 43]
  }
)