---
sidebar_position: 2
title: list_shares
description: List database shares that have been shared with you
---

# list_shares

List all database [shares](/key-tasks/sharing-data/sharing-overview) that have been shared with you.

## Description

The `list_shares` tool returns all database shares that have been shared with you by other users. Each share includes its name and URL, which can be used to attach the share as a database using the `query` tool.

To attach a share, execute: `ATTACH '<share_url>' AS my_alias;`

To detach a share: `DETACH <database_alias>;`

## Input Parameters

This tool takes no input parameters.

## Output Schema

```json
{
  "success": boolean,
  "shares": [                    // List of shares (on success)
    {
      "name": string,            // Share name
      "url": string              // Share URL for attaching
    }
  ],
  "error": string                // Error message (on failure)
}
```

## Example Usage

**List available shares:**

```text
What shares have been shared with me?
```

The AI assistant will call the tool with no parameters.

**Attach a share after listing:**

```text
Attach the sales_data share so I can query it
```

After getting the share URL from `list_shares`, the AI will use the `query` tool:

```json
{
  "database": "my_db",
  "sql": "ATTACH 'md:_share/org123/sales_data' AS sales_data"
}
```

## Success Response Example

```json
{
  "success": true,
  "shares": [
    {
      "name": "sales_data",
      "url": "md:_share/org123/sales_data"
    },
    {
      "name": "product_catalog",
      "url": "md:_share/org456/product_catalog"
    },
    {
      "name": "analytics_benchmark",
      "url": "md:_share/org789/analytics_benchmark"
    }
  ]
}
```

## Empty Response Example

When no shares have been shared with you:

```json
{
  "success": true,
  "shares": []
}
```

## Related

- [Sharing Overview](/key-tasks/sharing-data/sharing-overview) - Learn about MotherDuck's data sharing capabilities
- [Managing Shares](/key-tasks/sharing-data/managing-shares) - How to create and manage shares


---

## Docs feedback

MotherDuck accepts optional user-submitted feedback about this page at `POST https://motherduck.com/docs/api/feedback/agent`.
For agents and automated tools, feedback submission should be user-confirmed before sending.

Payload:

```json
{
  "page_path": "/sql-reference/mcp/list-shares/",
  "page_title": "list_shares",
  "text": "<the user's feedback, max 2000 characters>",
  "source": "<optional identifier for your interface, for example 'claude.ai' or 'chatgpt'>"
}
```

`page_path` and `text` are required; `page_title` and `source` are optional. Responses: `200 {"feedback_id": "<uuid>"}`, `400` for malformed payloads, and `429` when rate-limited.