vizro-mcp 0.1.0__tar.gz → 0.1.2__tar.gz
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- vizro_mcp-0.1.2/.dockerignore +10 -0
- vizro_mcp-0.1.2/CHANGELOG.md +34 -0
- vizro_mcp-0.1.2/Dockerfile +10 -0
- {vizro_mcp-0.1.0 → vizro_mcp-0.1.2}/PKG-INFO +87 -43
- {vizro_mcp-0.1.0 → vizro_mcp-0.1.2}/README.md +85 -41
- vizro_mcp-0.1.2/assets/vizro-mcp.gif +0 -0
- vizro_mcp-0.1.2/glama.json +4 -0
- {vizro_mcp-0.1.0 → vizro_mcp-0.1.2}/pyproject.toml +1 -1
- {vizro_mcp-0.1.0 → vizro_mcp-0.1.2}/src/vizro_mcp/__init__.py +1 -1
- vizro_mcp-0.1.2/src/vizro_mcp/_schemas/__init__.py +11 -0
- vizro_mcp-0.1.2/src/vizro_mcp/_schemas/schemas.py +214 -0
- {vizro_mcp-0.1.0 → vizro_mcp-0.1.2}/src/vizro_mcp/_utils/__init__.py +24 -5
- vizro_mcp-0.1.2/src/vizro_mcp/_utils/configs.py +142 -0
- vizro_mcp-0.1.2/src/vizro_mcp/_utils/prompts.py +180 -0
- {vizro_mcp-0.1.0 → vizro_mcp-0.1.2}/src/vizro_mcp/_utils/utils.py +63 -146
- vizro_mcp-0.1.2/src/vizro_mcp/server.py +364 -0
- {vizro_mcp-0.1.0 → vizro_mcp-0.1.2}/tests/unit/vizro_mcp/test_server.py +144 -66
- {vizro_mcp-0.1.0 → vizro_mcp-0.1.2}/uv.lock +713 -743
- vizro_mcp-0.1.0/CHANGELOG.md +0 -10
- vizro_mcp-0.1.0/src/vizro_mcp/_schemas/__init__.py +0 -29
- vizro_mcp-0.1.0/src/vizro_mcp/_schemas/schemas.py +0 -297
- vizro_mcp-0.1.0/src/vizro_mcp/server.py +0 -400
- {vizro_mcp-0.1.0 → vizro_mcp-0.1.2}/.gitignore +0 -0
- {vizro_mcp-0.1.0 → vizro_mcp-0.1.2}/LICENSE.txt +0 -0
- {vizro_mcp-0.1.0 → vizro_mcp-0.1.2}/assets/claude_prompt.png +0 -0
- {vizro_mcp-0.1.0 → vizro_mcp-0.1.2}/assets/claude_validate.png +0 -0
- {vizro_mcp-0.1.0 → vizro_mcp-0.1.2}/assets/claude_working.png +0 -0
- {vizro_mcp-0.1.0 → vizro_mcp-0.1.2}/assets/cursor_working.png +0 -0
- /vizro_mcp-0.1.0/changelog.d/20250506_175642_maximilian_schulz_0_1_0.md → /vizro_mcp-0.1.2/changelog.d/20250630_120648_maximilian_schulz_mcp.md +0 -0
- {vizro_mcp-0.1.0 → vizro_mcp-0.1.2}/changelog.d/new_fragment.md.j2 +0 -0
- {vizro_mcp-0.1.0 → vizro_mcp-0.1.2}/changelog.d/scriv.ini +0 -0
- {vizro_mcp-0.1.0 → vizro_mcp-0.1.2}/hatch.toml +0 -0
- {vizro_mcp-0.1.0 → vizro_mcp-0.1.2}/src/vizro_mcp/py.typed +0 -0
|
@@ -0,0 +1,34 @@
|
|
|
1
|
+
<a id='changelog-0.1.2'></a>
|
|
2
|
+
|
|
3
|
+
# 0.1.2 — 2025-06-30
|
|
4
|
+
|
|
5
|
+
## Added
|
|
6
|
+
|
|
7
|
+
- Add Dockerfile for Vizro MCP server to enable containerized local setup. ([#1184](https://github.com/mckinsey/vizro/pull/1184))
|
|
8
|
+
|
|
9
|
+
- Add capability to create custom charts (beyond Plotly Express) with Vizro-MCP. ([#1227](https://github.com/mckinsey/vizro/pull/1227))
|
|
10
|
+
|
|
11
|
+
## Changed
|
|
12
|
+
|
|
13
|
+
- Update Vizro version to `>=0.1.42`. ([#1227](https://github.com/mckinsey/vizro/pull/1227))
|
|
14
|
+
|
|
15
|
+
- Improve usability of MCP server in IDE environments like Cursor. ([#1227](https://github.com/mckinsey/vizro/pull/1227))
|
|
16
|
+
|
|
17
|
+
<a id='changelog-0.1.1'></a>
|
|
18
|
+
|
|
19
|
+
# 0.1.1 — 2025-05-15
|
|
20
|
+
|
|
21
|
+
### Fixed
|
|
22
|
+
|
|
23
|
+
- Fix name conflict with `langchain` by avoiding use of conflicting parameter names in tools. ([#1177](https://github.com/mckinsey/vizro/pull/1177))
|
|
24
|
+
|
|
25
|
+
<a id='changelog-0.1.0'></a>
|
|
26
|
+
|
|
27
|
+
# 0.1.0 — 2025-05-06
|
|
28
|
+
|
|
29
|
+
## Added
|
|
30
|
+
|
|
31
|
+
- Initial release of the Vizro MCP server. ([#1125](https://github.com/mckinsey/vizro/pull/1125))
|
|
32
|
+
- still experimental, please provide feedback via [github issues](https://github.com/mckinsey/vizro/issues)
|
|
33
|
+
- pinned `vizro` version to `0.1.38`
|
|
34
|
+
- published with 6 tools and 3 prompt templates
|
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
Metadata-Version: 2.4
|
|
2
2
|
Name: vizro-mcp
|
|
3
|
-
Version: 0.1.
|
|
3
|
+
Version: 0.1.2
|
|
4
4
|
Summary: MCP server to help create Vizro dashboards and charts
|
|
5
5
|
Author: Vizro Team
|
|
6
6
|
License-File: LICENSE.txt
|
|
@@ -14,13 +14,28 @@ Requires-Dist: click>=8.1.7
|
|
|
14
14
|
Requires-Dist: httpx>=0.28.1
|
|
15
15
|
Requires-Dist: mcp[cli]>=1.6.0
|
|
16
16
|
Requires-Dist: pandas[excel,html,parquet]
|
|
17
|
-
Requires-Dist: vizro
|
|
17
|
+
Requires-Dist: vizro>=0.1.42
|
|
18
18
|
Description-Content-Type: text/markdown
|
|
19
19
|
|
|
20
|
+
<!-- <a href="https://glama.ai/mcp/servers/@mckinsey/vizro">
|
|
21
|
+
<img width="380" height="200" src="https://glama.ai/mcp/servers/@mckinsey/vizro/badge" />
|
|
22
|
+
</a> -->
|
|
23
|
+
|
|
20
24
|
# Vizro MCP server
|
|
21
25
|
|
|
22
26
|
Vizro-MCP is a [Model Context Protocol (MCP)](https://modelcontextprotocol.io/) server, which works alongside a LLM to help you create Vizro dashboards and charts.
|
|
23
27
|
|
|
28
|
+
<img src="assets/vizro-mcp.gif" width="600" alt="Vizro MCP Demo">
|
|
29
|
+
|
|
30
|
+
### Quick install
|
|
31
|
+
|
|
32
|
+
| Host | Prerequisite | Link | Notes |
|
|
33
|
+
| ----------------------------------------- | ------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------- |
|
|
34
|
+
| [Cursor](https://www.cursor.com/) | [uv](https://docs.astral.sh/uv/getting-started/installation/) | [](https://cursor.com/install-mcp?name=vizro-mcp&config=eyJjb21tYW5kIjoidXZ4IHZpenJvLW1jcCJ9) | |
|
|
35
|
+
| [VS Code](https://code.visualstudio.com/) | [uv](https://docs.astral.sh/uv/guides/tools/) | [](https://insiders.vscode.dev/redirect/mcp/install?name=vizro-mcp&config=%7B%22command%22%3A%22uvx%22%2C%22args%22%3A%5B%22vizro-mcp%22%5D%7D) | |
|
|
36
|
+
| [Cursor](https://www.cursor.com/) | [Docker](https://www.docker.com/get-started/) | [](https://cursor.com/install-mcp?name=vizro-mcp&config=eyJjb21tYW5kIjoiZG9ja2VyIHJ1biAtaSAtLXJtIG1jcC92aXpybyJ9) | For local data access, [mount your data directory](#setup-instructions) |
|
|
37
|
+
| [VS Code](https://code.visualstudio.com/) | [Docker](https://www.docker.com/get-started/) | [](https://insiders.vscode.dev/redirect/mcp/install?name=vizro-mcp&config=%7B%22command%22%3A%22docker%22%2C%22args%22%3A%5B%22run%22%2C%22-i%22%2C%22--rm%22%2C%22mcp%2Fvizro%22%5D%7D) | For local data access, [mount your data directory](#setup-instructions) |
|
|
38
|
+
|
|
24
39
|
## Features of Vizro-MCP
|
|
25
40
|
|
|
26
41
|
Vizro-MCP provides tools and templates to create a functioning Vizro chart or dashboard step by step. Benefits include:
|
|
@@ -47,25 +62,22 @@ Without Vizro-MCP, if you try to make a dashboard using an LLM, it could choose
|
|
|
47
62
|
|
|
48
63
|
## 🛠️ Get started
|
|
49
64
|
|
|
50
|
-
|
|
51
|
-
|
|
52
|
-
### Prerequisites
|
|
65
|
+
Vizro-MCP can be run in two ways: using [`uvx`](https://docs.astral.sh/uv/guides/tools/) or using [`Docker`](https://www.docker.com/get-started/). It works with any MCP-enabled LLM client such as Cursor or Claude Desktop.
|
|
53
66
|
|
|
54
|
-
- [
|
|
55
|
-
- [Claude Desktop](https://claude.ai/download) or [Cursor](https://www.cursor.com/downloads)
|
|
67
|
+
If you want to run Vizro-MCP directly from source, skip to the end of this page to [Development or running from source](#development-or-running-from-source).
|
|
56
68
|
|
|
57
|
-
|
|
69
|
+
### Prerequisites
|
|
58
70
|
|
|
59
|
-
|
|
71
|
+
- [uv](https://docs.astral.sh/uv/getting-started/installation/) **or** [Docker](https://www.docker.com/get-started/)
|
|
72
|
+
- Any LLM application that supports MCP, such as [Claude Desktop](https://claude.ai/download) or [Cursor](https://www.cursor.com/downloads)
|
|
60
73
|
|
|
61
|
-
|
|
74
|
+
### Setup Instructions
|
|
62
75
|
|
|
63
|
-
|
|
76
|
+
The general server config is mostly the same for all hosts:
|
|
64
77
|
|
|
65
|
-
|
|
66
|
-
<summary><strong>Claude</strong></summary>
|
|
78
|
+
#### 1. Set up configuration
|
|
67
79
|
|
|
68
|
-
|
|
80
|
+
**Using `uvx`**
|
|
69
81
|
|
|
70
82
|
```json
|
|
71
83
|
{
|
|
@@ -80,44 +92,78 @@ Add the following to your `claude_desktop_config.json` [found via Developer Sett
|
|
|
80
92
|
}
|
|
81
93
|
```
|
|
82
94
|
|
|
83
|
-
|
|
84
|
-
|
|
85
|
-
If you are using Claude Desktop, restart it, and after a few moments, you should see the vizro-mcp menu when opening the settings/context menu:
|
|
86
|
-
|
|
87
|
-
<img src="assets/claude_working.png" alt="Claude Desktop MCP Server Icon" width="150"/>
|
|
88
|
-
|
|
89
|
-
</details>
|
|
90
|
-
|
|
91
|
-
<details>
|
|
92
|
-
<summary><strong>Cursor</strong></summary>
|
|
93
|
-
|
|
94
|
-
Add the following to `mcp.json` [found via the Cursor Settings](https://docs.cursor.com/context/model-context-protocol#configuration-locations).
|
|
95
|
+
**Using `Docker`**
|
|
95
96
|
|
|
96
97
|
```json
|
|
97
98
|
{
|
|
98
99
|
"mcpServers": {
|
|
99
100
|
"vizro-mcp": {
|
|
100
|
-
"command": "
|
|
101
|
+
"command": "docker",
|
|
101
102
|
"args": [
|
|
102
|
-
"
|
|
103
|
+
"run",
|
|
104
|
+
"-i",
|
|
105
|
+
"--rm",
|
|
106
|
+
"--mount",
|
|
107
|
+
"type=bind,src=</absolute/path/to/allowed/dir>,dst=</absolute/path/to/allowed/dir>",
|
|
108
|
+
"--mount",
|
|
109
|
+
"type=bind,src=</absolute/path/to/data.csv>,dst=</absolute/path/to/data.csv>",
|
|
110
|
+
"mcp/vizro"
|
|
103
111
|
]
|
|
104
112
|
}
|
|
105
113
|
}
|
|
106
114
|
}
|
|
107
115
|
```
|
|
108
116
|
|
|
109
|
-
>
|
|
117
|
+
> To use local data with Vizro-MCP, mount your data directory or directories into the container. Replace `</absolute/path/to/allowed/dir>` (syntax for folders) or `</absolute/path/to/data.csv>` (syntax for files) with the absolute path to your data on your machine. For consistency, it is recommended that the `dst` path matches the `src` path.
|
|
118
|
+
|
|
119
|
+
#### 2. Add the Configuration to MCP enabled LLM applications
|
|
110
120
|
|
|
111
|
-
|
|
121
|
+
In principle, the Vizro MCP server works with _any_ MCP enabled LLM applications but we recommend Claude Desktop or Cursor as popular choices (see more detailed instructions below). Different AI tools may use different setup methods or connection settings. Check each tool's docs for details.
|
|
122
|
+
|
|
123
|
+
<details>
|
|
124
|
+
<summary><strong>Claude Desktop</strong></summary>
|
|
112
125
|
|
|
113
|
-
|
|
126
|
+
- Add the configuration to your `claude_desktop_config.json` ([found via Developer Settings](https://modelcontextprotocol.io/quickstart/user#2-add-the-filesystem-mcp-server)).
|
|
127
|
+
|
|
128
|
+
- Restart Claude Desktop. After a few moments, you should see the vizro-mcp menu in the settings/context menu:
|
|
129
|
+
|
|
130
|
+
<img src="assets/claude_working.png" alt="Claude Desktop MCP Server Icon" width="300"/>
|
|
131
|
+
|
|
132
|
+
> ⚠️ **Warning:** In some hosts (like Claude Desktop) the free plan might be less performant, which may cause issues when the request is too complex. In cases where the request causes the UI to crash, opt for using a paid plan, or reduce your request's complexity.
|
|
133
|
+
|
|
134
|
+
</details>
|
|
135
|
+
|
|
136
|
+
<details>
|
|
137
|
+
<summary><strong>Cursor</strong></summary>
|
|
138
|
+
<br >
|
|
139
|
+
|
|
140
|
+
[](https://cursor.com/install-mcp?name=vizro-mcp&config=eyJjb21tYW5kIjoidXZ4IHZpenJvLW1jcCJ9)
|
|
141
|
+
|
|
142
|
+
- Add the above configuration to your `mcp.json` ([see Cursor Settings](https://docs.cursor.com/context/model-context-protocol#configuration-locations)) or click the button above.
|
|
143
|
+
|
|
144
|
+
- After a short pause, you should see a green light in the MCP menu:
|
|
145
|
+
|
|
146
|
+
|
|
114
147
|
|
|
115
148
|
</details>
|
|
116
149
|
|
|
117
|
-
|
|
150
|
+
<details>
|
|
151
|
+
<summary><strong>Other MCP Clients</strong></summary>
|
|
152
|
+
|
|
153
|
+
<br />
|
|
154
|
+
|
|
155
|
+
[](https://insiders.vscode.dev/redirect/mcp/install?name=vizro-mcp&config=%7B%22command%22%3A%22uvx%22%2C%22args%22%3A%5B%22vizro-mcp%22%5D%7D)
|
|
156
|
+
|
|
157
|
+
- Add the configuration as per your client's documentation.
|
|
158
|
+
|
|
159
|
+
- Check your client's documentation for where to place the config and how to verify the server is running.
|
|
160
|
+
|
|
161
|
+
</details>
|
|
118
162
|
|
|
119
163
|
## 💻 Usage
|
|
120
164
|
|
|
165
|
+
The MCP server is designed to get you started on Vizro dashboards and charts by creating beautiful working dashboards based on the core Vizro features. It is not designed to replace a human developer when going beyond the core features, e.g. when building an application that requires custom CSS or bespoke Dash components.
|
|
166
|
+
|
|
121
167
|
### Use prompt templates to get specific dashboards quickly
|
|
122
168
|
|
|
123
169
|
Prompt templates are not available in all MCP hosts, but when they are, you can use them to get specific dashboards quickly. To access them (e.g. in Claude Desktop), click on the plus icon below the chat, and choose _`Add from vizro-mcp`_.
|
|
@@ -144,7 +190,7 @@ In general, it helps to specify Vizro in the prompt and to keep it as precise (a
|
|
|
144
190
|
|
|
145
191
|
### Get a live preview of your dashboard
|
|
146
192
|
|
|
147
|
-
When the LLM chooses to use the tool `
|
|
193
|
+
When the LLM chooses to use the tool `validate_dashboard_config`, and the tool executes successfully, the LLM will return a link to a live preview of the dashboard if only public data accessed via URL is used. By default, the LLM will even open the link in your browser for you unless you tell it not to. In Claude Desktop, you can see the output of the tool by opening the tool collapsible and scrolling down to the very bottom.
|
|
148
194
|
|
|
149
195
|
<img src="assets/claude_validate.png" width="300"/>
|
|
150
196
|
|
|
@@ -166,34 +212,32 @@ Alternatively, you can just ask in the chat, for example:
|
|
|
166
212
|
|
|
167
213
|
MCP servers are a relatively new concept, and it is important to be transparent about what the tools are capable of so you can make an informed choice as a user. Overall, the Vizro MCP server only reads data, and never writes, deletes or modifies any data on your machine.
|
|
168
214
|
|
|
169
|
-
In general the most critical part of the process is the `load_and_analyze_data` tool. This tool, running on your machine, will load local or remote data into a pandas DataFrame and provide a detailed analysis of its structure and content. It only uses `pd.read_xxx`, so in general there is no need to worry about privacy or data security.
|
|
215
|
+
In general the most critical part of the process is the `load_and_analyze_data` tool. This tool, running on your machine, will load local or remote data into a pandas DataFrame and provide a detailed analysis of its structure and content. It only uses `pd.read_xxx`, so in general there is no need to worry about privacy or data security. However, you should only run Vizro-MCP locally, not as a hosted server, because there is currently no authentication to manage access.
|
|
170
216
|
|
|
171
|
-
The second most critical part is the `
|
|
217
|
+
The second most critical part is the `validate_dashboard_config` tool. This tool will attempt to instantiate the Vizro model configuration and return the Python code and visualization link for valid configurations. If the configuration is valid, it will also return and attempt to open a link to a live preview of the dashboard, which will take you to [PyCafe](https://py.cafe). If you don't want to open the link, you can tell the LLM to not do so.
|
|
172
218
|
|
|
173
219
|
## Available Tools (if client allows)
|
|
174
220
|
|
|
175
221
|
The Vizro MCP server provides the following tools. In general you should not need to use them directly, but in special cases you could ask the LLM to call them directly to help it find its way.
|
|
176
222
|
|
|
177
223
|
- `get_vizro_chart_or_dashboard_plan` - Get a structured step-by-step plan for creating either a chart or dashboard. Provides guidance on the entire creation process.
|
|
178
|
-
- `
|
|
179
|
-
- `
|
|
180
|
-
- `
|
|
224
|
+
- `get_model_json_schema` - Retrieves the complete JSON schema for any specified Vizro model, useful for understanding required and optional parameters.
|
|
225
|
+
- `validate_dashboard_config` - Tests Vizro model configurations by attempting to instantiate them. Returns Python code and visualization links for valid configurations.
|
|
226
|
+
- `load_and_analyze_data` - Loads a CSV file from a local path or URL into a pandas DataFrame and provides detailed analysis of its structure and content.
|
|
181
227
|
- `validate_chart_code` - Validates the code created for a chart and returns feedback on its correctness.
|
|
182
228
|
- `get_sample_data_info` - Provides information about sample datasets that can be used for testing and development.
|
|
183
229
|
|
|
184
230
|
## Available Prompts (if client allows)
|
|
185
231
|
|
|
186
232
|
- `create_starter_dashboard` - Use this prompt template to get started with Vizro dashboards.
|
|
187
|
-
- `
|
|
233
|
+
- `create_dashboard` - Use this prompt template to create a dashboard based on a local or remote CSV dataset.
|
|
188
234
|
- `create_vizro_chart` - Use this prompt template to create a Vizro styled plotly chart based on a local or remote CSV dataset.
|
|
189
235
|
|
|
190
236
|
## Development or running from source
|
|
191
237
|
|
|
192
|
-
If you are a developer, or if you are running Vizro-MCP from source, you need to clone the Vizro repo. To configure the Vizro
|
|
193
|
-
|
|
194
|
-
**For Claude**: Add the following to your `claude_desktop_config.json` [found via Developer Settings](https://modelcontextprotocol.io/quickstart/user#2-add-the-filesystem-mcp-server):
|
|
238
|
+
If you are a developer, or if you are running Vizro-MCP from source, you need to clone the Vizro repo. To configure the Vizro-MCP server details:
|
|
195
239
|
|
|
196
|
-
|
|
240
|
+
Add the following to your MCP configuration:
|
|
197
241
|
|
|
198
242
|
```json
|
|
199
243
|
{
|
|
@@ -1,7 +1,22 @@
|
|
|
1
|
+
<!-- <a href="https://glama.ai/mcp/servers/@mckinsey/vizro">
|
|
2
|
+
<img width="380" height="200" src="https://glama.ai/mcp/servers/@mckinsey/vizro/badge" />
|
|
3
|
+
</a> -->
|
|
4
|
+
|
|
1
5
|
# Vizro MCP server
|
|
2
6
|
|
|
3
7
|
Vizro-MCP is a [Model Context Protocol (MCP)](https://modelcontextprotocol.io/) server, which works alongside a LLM to help you create Vizro dashboards and charts.
|
|
4
8
|
|
|
9
|
+
<img src="assets/vizro-mcp.gif" width="600" alt="Vizro MCP Demo">
|
|
10
|
+
|
|
11
|
+
### Quick install
|
|
12
|
+
|
|
13
|
+
| Host | Prerequisite | Link | Notes |
|
|
14
|
+
| ----------------------------------------- | ------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------- |
|
|
15
|
+
| [Cursor](https://www.cursor.com/) | [uv](https://docs.astral.sh/uv/getting-started/installation/) | [](https://cursor.com/install-mcp?name=vizro-mcp&config=eyJjb21tYW5kIjoidXZ4IHZpenJvLW1jcCJ9) | |
|
|
16
|
+
| [VS Code](https://code.visualstudio.com/) | [uv](https://docs.astral.sh/uv/guides/tools/) | [](https://insiders.vscode.dev/redirect/mcp/install?name=vizro-mcp&config=%7B%22command%22%3A%22uvx%22%2C%22args%22%3A%5B%22vizro-mcp%22%5D%7D) | |
|
|
17
|
+
| [Cursor](https://www.cursor.com/) | [Docker](https://www.docker.com/get-started/) | [](https://cursor.com/install-mcp?name=vizro-mcp&config=eyJjb21tYW5kIjoiZG9ja2VyIHJ1biAtaSAtLXJtIG1jcC92aXpybyJ9) | For local data access, [mount your data directory](#setup-instructions) |
|
|
18
|
+
| [VS Code](https://code.visualstudio.com/) | [Docker](https://www.docker.com/get-started/) | [](https://insiders.vscode.dev/redirect/mcp/install?name=vizro-mcp&config=%7B%22command%22%3A%22docker%22%2C%22args%22%3A%5B%22run%22%2C%22-i%22%2C%22--rm%22%2C%22mcp%2Fvizro%22%5D%7D) | For local data access, [mount your data directory](#setup-instructions) |
|
|
19
|
+
|
|
5
20
|
## Features of Vizro-MCP
|
|
6
21
|
|
|
7
22
|
Vizro-MCP provides tools and templates to create a functioning Vizro chart or dashboard step by step. Benefits include:
|
|
@@ -28,25 +43,22 @@ Without Vizro-MCP, if you try to make a dashboard using an LLM, it could choose
|
|
|
28
43
|
|
|
29
44
|
## 🛠️ Get started
|
|
30
45
|
|
|
31
|
-
|
|
32
|
-
|
|
33
|
-
### Prerequisites
|
|
46
|
+
Vizro-MCP can be run in two ways: using [`uvx`](https://docs.astral.sh/uv/guides/tools/) or using [`Docker`](https://www.docker.com/get-started/). It works with any MCP-enabled LLM client such as Cursor or Claude Desktop.
|
|
34
47
|
|
|
35
|
-
- [
|
|
36
|
-
- [Claude Desktop](https://claude.ai/download) or [Cursor](https://www.cursor.com/downloads)
|
|
48
|
+
If you want to run Vizro-MCP directly from source, skip to the end of this page to [Development or running from source](#development-or-running-from-source).
|
|
37
49
|
|
|
38
|
-
|
|
50
|
+
### Prerequisites
|
|
39
51
|
|
|
40
|
-
|
|
52
|
+
- [uv](https://docs.astral.sh/uv/getting-started/installation/) **or** [Docker](https://www.docker.com/get-started/)
|
|
53
|
+
- Any LLM application that supports MCP, such as [Claude Desktop](https://claude.ai/download) or [Cursor](https://www.cursor.com/downloads)
|
|
41
54
|
|
|
42
|
-
|
|
55
|
+
### Setup Instructions
|
|
43
56
|
|
|
44
|
-
|
|
57
|
+
The general server config is mostly the same for all hosts:
|
|
45
58
|
|
|
46
|
-
|
|
47
|
-
<summary><strong>Claude</strong></summary>
|
|
59
|
+
#### 1. Set up configuration
|
|
48
60
|
|
|
49
|
-
|
|
61
|
+
**Using `uvx`**
|
|
50
62
|
|
|
51
63
|
```json
|
|
52
64
|
{
|
|
@@ -61,44 +73,78 @@ Add the following to your `claude_desktop_config.json` [found via Developer Sett
|
|
|
61
73
|
}
|
|
62
74
|
```
|
|
63
75
|
|
|
64
|
-
|
|
65
|
-
|
|
66
|
-
If you are using Claude Desktop, restart it, and after a few moments, you should see the vizro-mcp menu when opening the settings/context menu:
|
|
67
|
-
|
|
68
|
-
<img src="assets/claude_working.png" alt="Claude Desktop MCP Server Icon" width="150"/>
|
|
69
|
-
|
|
70
|
-
</details>
|
|
71
|
-
|
|
72
|
-
<details>
|
|
73
|
-
<summary><strong>Cursor</strong></summary>
|
|
74
|
-
|
|
75
|
-
Add the following to `mcp.json` [found via the Cursor Settings](https://docs.cursor.com/context/model-context-protocol#configuration-locations).
|
|
76
|
+
**Using `Docker`**
|
|
76
77
|
|
|
77
78
|
```json
|
|
78
79
|
{
|
|
79
80
|
"mcpServers": {
|
|
80
81
|
"vizro-mcp": {
|
|
81
|
-
"command": "
|
|
82
|
+
"command": "docker",
|
|
82
83
|
"args": [
|
|
83
|
-
"
|
|
84
|
+
"run",
|
|
85
|
+
"-i",
|
|
86
|
+
"--rm",
|
|
87
|
+
"--mount",
|
|
88
|
+
"type=bind,src=</absolute/path/to/allowed/dir>,dst=</absolute/path/to/allowed/dir>",
|
|
89
|
+
"--mount",
|
|
90
|
+
"type=bind,src=</absolute/path/to/data.csv>,dst=</absolute/path/to/data.csv>",
|
|
91
|
+
"mcp/vizro"
|
|
84
92
|
]
|
|
85
93
|
}
|
|
86
94
|
}
|
|
87
95
|
}
|
|
88
96
|
```
|
|
89
97
|
|
|
90
|
-
>
|
|
98
|
+
> To use local data with Vizro-MCP, mount your data directory or directories into the container. Replace `</absolute/path/to/allowed/dir>` (syntax for folders) or `</absolute/path/to/data.csv>` (syntax for files) with the absolute path to your data on your machine. For consistency, it is recommended that the `dst` path matches the `src` path.
|
|
99
|
+
|
|
100
|
+
#### 2. Add the Configuration to MCP enabled LLM applications
|
|
91
101
|
|
|
92
|
-
|
|
102
|
+
In principle, the Vizro MCP server works with _any_ MCP enabled LLM applications but we recommend Claude Desktop or Cursor as popular choices (see more detailed instructions below). Different AI tools may use different setup methods or connection settings. Check each tool's docs for details.
|
|
103
|
+
|
|
104
|
+
<details>
|
|
105
|
+
<summary><strong>Claude Desktop</strong></summary>
|
|
93
106
|
|
|
94
|
-
|
|
107
|
+
- Add the configuration to your `claude_desktop_config.json` ([found via Developer Settings](https://modelcontextprotocol.io/quickstart/user#2-add-the-filesystem-mcp-server)).
|
|
108
|
+
|
|
109
|
+
- Restart Claude Desktop. After a few moments, you should see the vizro-mcp menu in the settings/context menu:
|
|
110
|
+
|
|
111
|
+
<img src="assets/claude_working.png" alt="Claude Desktop MCP Server Icon" width="300"/>
|
|
112
|
+
|
|
113
|
+
> ⚠️ **Warning:** In some hosts (like Claude Desktop) the free plan might be less performant, which may cause issues when the request is too complex. In cases where the request causes the UI to crash, opt for using a paid plan, or reduce your request's complexity.
|
|
114
|
+
|
|
115
|
+
</details>
|
|
116
|
+
|
|
117
|
+
<details>
|
|
118
|
+
<summary><strong>Cursor</strong></summary>
|
|
119
|
+
<br >
|
|
120
|
+
|
|
121
|
+
[](https://cursor.com/install-mcp?name=vizro-mcp&config=eyJjb21tYW5kIjoidXZ4IHZpenJvLW1jcCJ9)
|
|
122
|
+
|
|
123
|
+
- Add the above configuration to your `mcp.json` ([see Cursor Settings](https://docs.cursor.com/context/model-context-protocol#configuration-locations)) or click the button above.
|
|
124
|
+
|
|
125
|
+
- After a short pause, you should see a green light in the MCP menu:
|
|
126
|
+
|
|
127
|
+
|
|
95
128
|
|
|
96
129
|
</details>
|
|
97
130
|
|
|
98
|
-
|
|
131
|
+
<details>
|
|
132
|
+
<summary><strong>Other MCP Clients</strong></summary>
|
|
133
|
+
|
|
134
|
+
<br />
|
|
135
|
+
|
|
136
|
+
[](https://insiders.vscode.dev/redirect/mcp/install?name=vizro-mcp&config=%7B%22command%22%3A%22uvx%22%2C%22args%22%3A%5B%22vizro-mcp%22%5D%7D)
|
|
137
|
+
|
|
138
|
+
- Add the configuration as per your client's documentation.
|
|
139
|
+
|
|
140
|
+
- Check your client's documentation for where to place the config and how to verify the server is running.
|
|
141
|
+
|
|
142
|
+
</details>
|
|
99
143
|
|
|
100
144
|
## 💻 Usage
|
|
101
145
|
|
|
146
|
+
The MCP server is designed to get you started on Vizro dashboards and charts by creating beautiful working dashboards based on the core Vizro features. It is not designed to replace a human developer when going beyond the core features, e.g. when building an application that requires custom CSS or bespoke Dash components.
|
|
147
|
+
|
|
102
148
|
### Use prompt templates to get specific dashboards quickly
|
|
103
149
|
|
|
104
150
|
Prompt templates are not available in all MCP hosts, but when they are, you can use them to get specific dashboards quickly. To access them (e.g. in Claude Desktop), click on the plus icon below the chat, and choose _`Add from vizro-mcp`_.
|
|
@@ -125,7 +171,7 @@ In general, it helps to specify Vizro in the prompt and to keep it as precise (a
|
|
|
125
171
|
|
|
126
172
|
### Get a live preview of your dashboard
|
|
127
173
|
|
|
128
|
-
When the LLM chooses to use the tool `
|
|
174
|
+
When the LLM chooses to use the tool `validate_dashboard_config`, and the tool executes successfully, the LLM will return a link to a live preview of the dashboard if only public data accessed via URL is used. By default, the LLM will even open the link in your browser for you unless you tell it not to. In Claude Desktop, you can see the output of the tool by opening the tool collapsible and scrolling down to the very bottom.
|
|
129
175
|
|
|
130
176
|
<img src="assets/claude_validate.png" width="300"/>
|
|
131
177
|
|
|
@@ -147,34 +193,32 @@ Alternatively, you can just ask in the chat, for example:
|
|
|
147
193
|
|
|
148
194
|
MCP servers are a relatively new concept, and it is important to be transparent about what the tools are capable of so you can make an informed choice as a user. Overall, the Vizro MCP server only reads data, and never writes, deletes or modifies any data on your machine.
|
|
149
195
|
|
|
150
|
-
In general the most critical part of the process is the `load_and_analyze_data` tool. This tool, running on your machine, will load local or remote data into a pandas DataFrame and provide a detailed analysis of its structure and content. It only uses `pd.read_xxx`, so in general there is no need to worry about privacy or data security.
|
|
196
|
+
In general the most critical part of the process is the `load_and_analyze_data` tool. This tool, running on your machine, will load local or remote data into a pandas DataFrame and provide a detailed analysis of its structure and content. It only uses `pd.read_xxx`, so in general there is no need to worry about privacy or data security. However, you should only run Vizro-MCP locally, not as a hosted server, because there is currently no authentication to manage access.
|
|
151
197
|
|
|
152
|
-
The second most critical part is the `
|
|
198
|
+
The second most critical part is the `validate_dashboard_config` tool. This tool will attempt to instantiate the Vizro model configuration and return the Python code and visualization link for valid configurations. If the configuration is valid, it will also return and attempt to open a link to a live preview of the dashboard, which will take you to [PyCafe](https://py.cafe). If you don't want to open the link, you can tell the LLM to not do so.
|
|
153
199
|
|
|
154
200
|
## Available Tools (if client allows)
|
|
155
201
|
|
|
156
202
|
The Vizro MCP server provides the following tools. In general you should not need to use them directly, but in special cases you could ask the LLM to call them directly to help it find its way.
|
|
157
203
|
|
|
158
204
|
- `get_vizro_chart_or_dashboard_plan` - Get a structured step-by-step plan for creating either a chart or dashboard. Provides guidance on the entire creation process.
|
|
159
|
-
- `
|
|
160
|
-
- `
|
|
161
|
-
- `
|
|
205
|
+
- `get_model_json_schema` - Retrieves the complete JSON schema for any specified Vizro model, useful for understanding required and optional parameters.
|
|
206
|
+
- `validate_dashboard_config` - Tests Vizro model configurations by attempting to instantiate them. Returns Python code and visualization links for valid configurations.
|
|
207
|
+
- `load_and_analyze_data` - Loads a CSV file from a local path or URL into a pandas DataFrame and provides detailed analysis of its structure and content.
|
|
162
208
|
- `validate_chart_code` - Validates the code created for a chart and returns feedback on its correctness.
|
|
163
209
|
- `get_sample_data_info` - Provides information about sample datasets that can be used for testing and development.
|
|
164
210
|
|
|
165
211
|
## Available Prompts (if client allows)
|
|
166
212
|
|
|
167
213
|
- `create_starter_dashboard` - Use this prompt template to get started with Vizro dashboards.
|
|
168
|
-
- `
|
|
214
|
+
- `create_dashboard` - Use this prompt template to create a dashboard based on a local or remote CSV dataset.
|
|
169
215
|
- `create_vizro_chart` - Use this prompt template to create a Vizro styled plotly chart based on a local or remote CSV dataset.
|
|
170
216
|
|
|
171
217
|
## Development or running from source
|
|
172
218
|
|
|
173
|
-
If you are a developer, or if you are running Vizro-MCP from source, you need to clone the Vizro repo. To configure the Vizro
|
|
174
|
-
|
|
175
|
-
**For Claude**: Add the following to your `claude_desktop_config.json` [found via Developer Settings](https://modelcontextprotocol.io/quickstart/user#2-add-the-filesystem-mcp-server):
|
|
219
|
+
If you are a developer, or if you are running Vizro-MCP from source, you need to clone the Vizro repo. To configure the Vizro-MCP server details:
|
|
176
220
|
|
|
177
|
-
|
|
221
|
+
Add the following to your MCP configuration:
|
|
178
222
|
|
|
179
223
|
```json
|
|
180
224
|
{
|
|
Binary file
|