joomla

This Joomla MCP Server exposes a set of tools that let an AI assistant interact with a Joomla site via its Web Services API. You can fetch all articles, list categories, create new articles, update existing ones, manage their publication state, and delete articles. The available tools include get_joomla_articles(), get_joomla_categories(), create_article(), manage_article_state(), delete_article(), and update_article(). To use the server, provide the Joomla base URL and a Bearer token for authentication. The AI can call these tools in natural language prompts; for example, asking to summarize all articles in a category might translate to get_joomla_articles() with appropriate filtering, while creating an article will map to create_article() with the required article_text and optional title or category_id. Ensure your Joomla site has the Web Services API plugin enabled and that you supply valid authentication credentials via the BEARER_TOKEN env var.

Prerequisites:\n- Python 3.11+ (or higher) installed on your machine.\n- Access to install and run uv (Python dependency manager) as described below.\n\nInstall and set up locally:\n1) Clone the repository:\nbash\ngit clone https://github.com/nasoma/joomla-mcp-server.git\ncd joomla-mcp-server\n\n2) Install uv if you don’t have it, then sync dependencies:\nbash\npipx install uvx # or follow uv installation instructions for your environment\nuv sync\n\n3) Run the server with uv (from the repository root):\nbash\nuv --directory <path-to-project> run main.py\n\n4) Prepare environment variables (example):\nbash\nexport JOOMLA_BASE_URL=https://your-joomla-site.com\nexport BEARER_TOKEN=your_api_token\n\n5) Optional: integrate with Claude or other assistants by providing the path to uv and project directory in your assistant’s config (see the example in the README).\n\nNotes:\n- Ensure the Joomla Web Services API plugin is enabled on your site.\n- Use HTTPS to protect API communications.\n- The token should be treated as a sensitive credential.

Tips and considerations:\n- The server expects JOOMLA_BASE_URL and BEARER_TOKEN environment variables; never commit tokens to code.\n- When creating or updating articles, provide introtext and fulltext as required by Joomla’s article structure; include a Read More break between them for proper rendering.\n- For delete and state changes, ensure you have appropriate permissions on the Joomla site.\n- If you encounter authentication errors, verify that the token is valid and that the API endpoint URL is correct.\n- If you run into CORS or network issues from an AI environment, ensure the hosting environment allows outbound HTTPS requests to your Joomla site.\n- The MCP server sanitizes HTML content to prevent XSS; still validate inputs when composing article content.\n- If you update the server or dependencies, re-run uv sync to refresh the environment.\n