Same category · Data / Analytics
by easecloudio · easecloudio/mcp-metabase-server
Connect to Metabase through the EaseCloud community MCP server, starting with read-only dashboard discovery.
Configure the EaseCloud Metabase server, check a metadata-only request, and troubleshoot authentication separately from Metabase’s built-in OAuth MCP.
Documentation and source review: 2026-10-13. No server or export was run for this guide. GitHub stars: 82 (collected 2026-10-13).
This page covers the EaseCloud community package, @easecloudio/mcp-metabase-server. The repository package metadata declares version 1.3.0. The configuration below follows the author’s npx setup; npx resolves the published package when your client starts it.
Merge this mcpServers entry into your Claude Desktop configuration, replace the example URL and API key, then fully restart the client. On macOS the file is ~/Library/Application Support/Claude/claude_desktop_config.json; on Windows it is %APPDATA%/Claude/claude_desktop_config.json.
METABASE_URL is required. Supply METABASE_API_KEY, or use both METABASE_USERNAME and METABASE_PASSWORD instead. The source sends API keys in X-API-Key; the password fallback obtains a session through /api/session.
The author documents Metabase 0.46.x and later, with 0.48.x or later recommended. TOOL_MODE=read filters out destructive tools; it does not replace Metabase access permissions. Keep the initial prompt to metadata discovery.
{
"mcpServers": {
"metabase-easecloud": {
"command": "npx",
"args": [
"-y",
"@easecloudio/mcp-metabase-server"
],
"env": {
"METABASE_URL": "https://your-metabase.example.com",
"METABASE_API_KEY": "your_metabase_api_key",
"TOOL_MODE": "read"
}
}
}
}{
"METABASE_URL": "https://your-metabase.example.com",
"METABASE_USERNAME": "your_username",
"METABASE_PASSWORD": "your_password",
"TOOL_MODE": "read"
}Sources: EaseCloud README · Package metadata · Configuration source · Authentication source · Tool filtering source · Checked 2026-10-13.
After the client discovers the tools, start with list_dashboards and an empty argument object. A successful connection means the tool is discovered and the call returns a dashboard list without a transport or authentication error. An empty list can be valid when the account has no visible dashboards.
This is a suggested check based on documented tool behavior, not a recorded run. Compare any returned dashboard IDs and names with what the same account can see in Metabase.
Use metabase-easecloud to call list_dashboards with {}. Show only dashboard IDs and names. Do not execute SQL, create, edit, or delete anything.{}Sources: EaseCloud README · Tool filtering source · Checked 2026-10-13.
| Tool | Purpose |
|---|---|
| list_dashboards | Find available dashboards. |
| get_dashboard | Read one dashboard by ID. |
| list_databases | Inspect available database connections. |
| get_database_schema | Inspect a database schema. |
Sources: EaseCloud README · Checked 2026-10-13.
Use a Metabase identity with access appropriate to the data you want to inspect. Keep credentials in the client configuration rather than prompts or committed example files. This server calls your Metabase API; any returned data is then available to your MCP client.
TOOL_MODE defaults to all. Use read for the metadata example above. The essential mode includes execution tools, so do not treat that mode as a metadata-only permission boundary.
Sources: Authentication source · Tool filtering source · Checked 2026-10-13.
| Symptom | Check | Success signal |
|---|---|---|
| Package cannot be resolved | Use the exact scoped name @easecloudio/mcp-metabase-server, not this page’s slug. Check that npx is available to the client. | The client starts the server and discovers tools. |
| METABASE_URL or credential error | Set METABASE_URL and one complete authentication method in the server environment. Restart the client. | No missing-environment error on startup. |
| Authentication failed or denied API request | Check the same Metabase address and credentials against your instance. The API key uses X-API-Key; password authentication calls /api/session. Inspect the client server log. | The metadata call succeeds for the intended account. |
| Tool not available in TOOL_MODE | read hides destructive tools; the registry also hides tools without mode metadata. Do not switch to all just to test connection. | list_dashboards is available and callable. |
| Version or endpoint mismatch | Compare your instance version with the author’s supported versions. The community server calls the REST API, not /api/metabase-mcp. | A documented metadata tool works against your instance. |
Sources: Configuration source · Authentication source · Tool filtering source · EaseCloud README · Checked 2026-10-13.
The current Metabase documentation describes an embedded MCP server at https://your-metabase.example.com/api/metabase-mcp. An administrator enables it under Admin > AI > MCP, with AI features enabled. Clients authenticate through Metabase OAuth and the connecting person’s permissions.
Do not reuse the community package’s METABASE_API_KEY environment as authentication for this endpoint. For Claude Code, add the HTTP server, open /mcp, select it, and Authenticate. The current documentation notes that connections made before Metabase 0.64 need to sign in again after upgrading.
For a local or containerized built-in server, a “Failed to connect” error before the OAuth prompt can mean the Site URL is unreachable from the client. Set MB_SITE_URL on the Metabase instance to the client-reachable base URL. This setting belongs to Metabase, not the EaseCloud process.
Built-in success criterion: OAuth finishes and the agent can invoke a Metabase tool. Some clients do not support localhost connections; check the documented client restrictions. A missing visualize_query tool in a client without inline-chart support is expected.
claude mcp add --transport http metabase-builtin https://your-metabase.example.com/api/metabase-mcp{
"MB_SITE_URL": "http://localhost:3000"
}Sources: Metabase MCP documentation · Checked 2026-10-13.