Matomo MCP Plugin
A complete Model Context Protocol (MCP) server implementation for Matomo that works out of the box with any AI model. No configuration files or NPM requirements needed on the client side - just copy and paste a URL with your API token.
Features
Complete MCP Server: Full implementation of MCP protocol with tools, prompts, and resources
Zero Configuration: Works immediately after plugin installation
HTTP-Based: No WebSocket or stdio transport required
Secure Authentication: Uses Matomo's built-in API token system
Extensible Architecture: Easy to add new tools and prompts
Production Ready: Built following Matomo plugin best practices
Quick Start
1. Install the Plugin
Copy this plugin directory to your Matomo
plugins/
folderActivate the plugin in Matomo Admin � Plugins
2. Get Your API Token
Go to Matomo Admin � Personal � Security
Create or copy your API authentication token
3. Connect to AI Models
Claude Desktop Configuration
Add this to your Claude Desktop configuration:
Direct HTTP API Access
You can also integrate directly via HTTP POST requests to:
Available Tools
Analytics Data Tool (get_analytics_data
)
Get comprehensive analytics data from Matomo.
Parameters:
idSite
(integer): Site ID to get data forperiod
(string): Time period (day, week, month, year)date
(string): Date or date range (e.g., "2024-01-01" or "last7")metric
(string): Metric to retrieve (visits, pageviews, visitors, bounces, conversions)
Example:
Site Management Tool (manage_sites
)
Manage Matomo sites - list, create, update, or delete.
Parameters:
action
(string): Action to perform (list, create, update, delete, get)idSite
(integer): Site ID (for get, update, delete)siteName
(string): Site name (for create, update)urls
(array): Site URLs (for create, update)timezone
(string): Timezonecurrency
(string): Currency code
Available Prompts
Analytics Reporting (generate_analytics_report
)
Generate comprehensive analytics reports and insights.
Arguments:
report_type
: Type of report (summary, performance, growth, technical)site_data
: Analytics data for analysis
Available Resources
Sites Information (matomo://sites
)
List of all sites in your Matomo instance with basic information.
Server Configuration (matomo://config
)
Matomo server configuration and system information.
Authentication
The MCP server supports both OAuth 2.0 (recommended) and API Token authentication:
OAuth 2.0 (Recommended)
For production use and MCP client compatibility:
Register OAuth Client:
Authorization Flow:
Direct users to authorization URL
Exchange authorization code for access token
Use access token in API calls
Use Access Token:
With header: Authorization: Bearer YOUR_ACCESS_TOKEN
See OAuth Guide for complete implementation details.
API Token (Backward Compatibility)
For simple setups, use Matomo API tokens:
In request body:
In Authorization header:
Permissions & Scopes
OAuth Scope | API Token Equivalent | Permissions |
| View access | Analytics data, reports |
| Admin access | Modify settings, goals |
| Super user | Full admin access |
Development
Adding New Tools
Create a new PHP class in
/tools/
directoryImplement
getToolDefinition()
andexecute($params)
methodsThe tool will be automatically registered
Example tool structure:
Adding New Prompts
Create a new PHP class in
/prompts/
directoryImplement
getPromptDefinition()
andexecute($args)
methodsThe prompt will be automatically registered
API Endpoints
GET /index.php?module=MCP&action=capabilities
- Get server capabilitiesPOST /index.php?module=MCP&action=index
- Main MCP endpoint
Requirements
Matomo 5.0+
PHP 7.4+
Valid Matomo API token
License
GPL v3+ - Same as Matomo
Support
This server cannot be installed
Enables AI models to interact with Matomo analytics through a complete MCP server implementation. Provides tools for retrieving analytics data, managing sites, and generating reports with zero configuration setup.