How to Use the Matomo Alternative MCP in Pydantic AI

Q: What happens if the Matomo API changes and the Matomo Alternative report format is updated?

Your Pydantic AI agent will fail loudly with a ValidationError. This is a feature, not a bug. It prevents your application from silently accepting and processing malformed analytics data, alerting you that the tool's response schema needs to be updated.

Q: Can I get type-safe reports with the Matomo Alternative and Pydantic AI from WordPress?

You bet. The getwpprocessedreport tool is fully compatible. Pydantic AI will validate its output, so you get the same guarantee of data correctness for reports coming from your WordPress-based Matomo setup.

Add type-safe Matomo analytics to any LLM with Pydantic AI and get responses that are guaranteed correct.

See Vinkius in Action

Works with every AI agent you already use

…and any MCP-compatible client

MCP Servers - Free for Subscribers

Connect Matomo Alternative MCP to Pydantic AI

Create your Vinkius account to connect Matomo Alternative to Pydantic AI and route execution through our secure gateway. The platform manages server hosting, runtime updates, and security layers. Configuration requires no manual server provisioning.

GDPR Free for Subscribers

Setup Matomo Alternative with Pydantic AI

Ask AI about this MCP

ChatGPT

Claude

Perplexity

Get Analytics Data That Won't Break Your Code

Pydantic AI validates every response from this server against a Pydantic model. When your agent calls `get_visits_summary`, you don't get a blob of JSON; you get a typed object. If the API ever returns something unexpected, your code raises a `ValidationError` immediately. This means no more silent data corruption or defensive coding against weird API outputs. Your agent can confidently work with the metrics from `get_processed_report` or `get_wp_processed_report`, knowing the data structure is exactly what it expects. It's reliability by default.

Track Events with Confidence

Use the `track_action` and `track_bulk` tools to log user behavior from your agent. Pydantic AI's structure helps ensure your agent sends the correct parameters, like the required `idsite`, every time. This isn't just about sending data; it's about accountable tracking. Because you can use Pydantic AI with any LLM—OpenAI, local models, anything—you can build a consistent, reliable tracking layer that isn't tied to a single model provider. The correctness comes from the framework, not the LLM.

An MCP Server That Is Model-Agnostic

This MCP server exposes analytics tools that your Pydantic AI agent can use, regardless of the underlying LLM. Your agent can discover what reports are available with `get_report_metadata` and then fetch them. You can swap from GPT-4 to a local Llama model without changing a single line of your tool-using code. The Pydantic AI framework and this MCP server provide a stable, predictable interface for your agent to interact with your Matomo analytics.

Setup guide

Set up Matomo Alternative MCP in Pydantic AI

Prerequisites

Python 3.10+ installed
pydantic-ai-slim[fastmcp] package
Active Vinkius subscription with a valid endpoint token

1

Install Pydantic AI with FastMCP
Run pip install "pydantic-ai-slim[fastmcp]". The FastMCP toolset replaces the deprecated MCPServerHTTP class with full protocol support.
2

Configure the FastMCPToolset
Pass a JSON-style config dict to FastMCPToolset with your Vinkius URL. Replace [YOUR_TOKEN_HERE] with your token from cloud.vinkius.com. Supports Streamable HTTP, SSE, and Stdio transports.
3

Create and run your agent
Pass the toolset to Agent(toolsets=[toolset]) and call agent.run(). Swap openai:gpt-4o for any supported model — Anthropic, Google, Mistral, or Groq.

agent.py

from pydantic_ai import Agent
from pydantic_ai.toolsets.fastmcp import FastMCPToolset

toolset = FastMCPToolset({
    "mcpServers": {
        "matomo-alternative-mcp": {
            "url": "https://edge.vinkius.com/[YOUR_TOKEN_HERE]/mcp"
        }
    }
})

agent = Agent(
    "openai:gpt-4o",
    toolsets=[toolset],
    system_prompt="You have access to Matomo Alternative tools.",
)

result = await agent.run("List recent Matomo Alternative transactions")
print(result.output)

Get your connection token →

Independent Platform Disclaimer: Vinkius is an independent platform and is not affiliated with, endorsed by, sponsored by, verified by, or otherwise authorized by Matomo. All third-party trademarks, logos, and brand names are the property of their respective owners. Their use on this website is strictly for informational purposes to identify service compatibility and interoperability.

Why Choose Vinkius

Vinkius connects your tools to AI with real-time monitoring and automatic cost savings — all from one dashboard.

Connect Matomo Alternative now

Real-time monitoring

Live

visibility into every interaction

Connect your favorite tools to your AI and see exactly what's happening — every request, every response, in real time.

Built-in savings

60%

lower AI costs

Vinkius compresses data between your apps and your AI automatically. Lower bills every month — no configuration required.

Single dashboard

One

place for every integration

Every tool your AI connects to, managed from a single screen. One account, complete control.

Common questions about Matomo Alternative MCP in Pydantic AI

Pydantic AI automatically validates the JSON output from tools like `get_visits_summary` against predefined Pydantic models. If the data doesn't match the expected schema, it raises an error instead of letting your agent proceed with bad data.

Yes. Pydantic AI is model-agnostic. You can connect it to a local model or any major provider, and it will be able to use the tools from this server, such as `track_action` and `get_processed_report`, in the same way.

Your Pydantic AI agent will fail loudly with a `ValidationError`. This is a feature, not a bug. It prevents your application from silently accepting and processing malformed analytics data, alerting you that the tool's response schema needs to be updated.

You bet. The `get_wp_processed_report` tool is fully compatible. Pydantic AI will validate its output, so you get the same guarantee of data correctness for reports coming from your WordPress-based Matomo setup.

The server is a pass-through. It operates within a zero-trust, ephemeral sandbox on Vinkius and doesn't store any of your analytics payloads. Your tracking data from tools like `track_bulk` is sent directly to your Matomo instance and is never persisted on our servers.

Use it with your favorite AI tools

Connect this server to Cursor, Claude, VS Code, and more.

OpenAI Agents SDK sdk-python

Google ADK sdk-python

Pydantic AI sdk-python

Vercel AI SDK sdk-typescript