# mcp-server-dash

**Repository Path**: mirrors_dropbox/mcp-server-dash

## Basic Information

- **Project Name**: mcp-server-dash
- **Description**: Dropbox Dash MCP Server
- **Primary Language**: Unknown
- **License**: Apache-2.0
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2025-10-23
- **Last Updated**: 2026-02-14

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# Dropbox Dash MCP Server

An MCP server that exposes Dropbox Dash search and file metadata via STDIO using the Python MCP server library (`fastmcp`). Authenticate with Dropbox, then search across all company content and fetch detailed file metadata and content.

## Tools Implemented

- `dash_get_auth_url`
  - Summary: Start Dropbox OAuth; returns the authorization URL.
  - Args: none
  - Returns (text): A short instruction message followed by the URL.
  - Notes: Use when not yet authenticated or when a token has expired. After approval in the browser, call `dash_authenticate` with the one-time code. Tokens are stored securely in your system keyring, so this is typically a one-time setup.

- `dash_authenticate`
  - Summary: Complete OAuth using the one-time authorization code.
  - Args:
    - `auth_code` (string, required)
  - Returns (text): Account display name and email on success; a human-readable error on failure.
  - Notes: Persists a token for subsequent tool calls. Typically only needed once until the token expires or is revoked.

- `dash_company_search`
  - Summary: Search company content indexed by Dropbox Dash.
  - Args:
    - `query` (string, required) — search text
    - `file_type` (string or null, optional) — one of: `document`, `image`, `video`, `audio`, `pdf`, `presentation`, `spreadsheet`; or `null` for no filter. Default: `null`. The value `document` is also treated as no filter.
    - `connector` (string or null, optional) — filter by connector source. Common connectors include `confluence`, `dropbox`, `github`, `gmail`, `gong`, `google_calendar`, `google_drive`, `jira`, `microsoft_365`, `microsoft_teams`, `slack`, `workday`, `zoom`, among others. Default: `null` for no connector filter.
    - `start_time` (string or null, optional) — filter results modified after this datetime (ISO 8601 format, e.g., `2025-10-30T16:24:12.071Z`). Default: `null` for no start time filter.
    - `end_time` (string or null, optional) — filter results modified before this datetime (ISO 8601 format, e.g., `2025-10-31T16:24:12.071Z`). Default: `null` for no end time filter.
    - `max_results` (integer, optional) — default `20`, range `1..100`
  - Returns (text): A formatted list of results. Each result includes labeled fields such as `UUID:`, `Type:`, `URL:`, `Preview:`, `Description:`, `File Type:`, `MIME Type:`, `Source:`, `Creator:`, `Last Modified By:`, `Updated:`, `Source Updated:`, `Relevance:`, `Source ID:`. Results are separated by a divider line.
  - Errors: Human-readable messages for invalid parameters or missing authentication.

- `dash_get_file_details`
  - Summary: Fetch detailed metadata (and optional content snippet) for a result UUID.
  - Args:
    - `uuid` (string, required) — UUID from search results
  - Returns (text): A summary with labeled fields (Title, Link, Updated, Source Updated, MIME Type, Source, Creator, Last Modified By). Media sections are included when present (Video/Image metadata). Content, when available, is shown with a MIME type and may be truncated to ~20,000 characters.
  - Errors: Human-readable messages for missing authentication or unknown UUID.

### First-Time (or Re-Auth) Flow

If the user is not yet authenticated (or the token has expired):
1) `dash_get_auth_url` → open the URL and approve access.
2) `dash_authenticate(auth_code)` → store the token.
3) Proceed with `dash_company_search(...)` and `dash_get_file_details(uuid)`.

## Prerequisites

Before installing and running the MCP server, you need to create a Dropbox app to obtain API credentials:

1. Go to [dropbox.com/developers/apps](https://www.dropbox.com/developers/apps)
2. Click on **Create app**
3. Select **Scoped access** as the API type
4. Choose **Full Dropbox** access
5. Give your app a name
6. After creating the app, go to the **Permissions** tab and enable:
   - `files.metadata.read`
   - `files.content.read`
7. Take note of the **App key** value from the **Settings** tab (you'll need this for configuration)

This credential will be used as `APP_KEY` in the installation steps below.

## Requirements

- Python 3.10 or higher
- Dropbox Dash API credentials (App key)
- Network access to Dropbox APIs

## Installation

### Clone the repository:

```
git clone https://github.com/dropbox/mcp-server-dash
cd mcp-server-dash
```

### Install `uv` for virtual environment and dependency management:

**macOS (Homebrew)**
```
brew install uv
```

**macOS/Linux**:
```
curl -LsSf https://astral.sh/uv/install.sh | sh
```

**Windows (PowerShell):**
```
irm https://astral.sh/uv/install.ps1 | iex
```

### Set up the virtual environment and install dependencies
```
uv sync
```

### Provide credentials (environment or `.env`)
```bash
export APP_KEY=your_dropbox_app_key
# or create a .env file with APP_KEY
# e.g., copy the example file:
cp .env.example .env
```

## Usage

### Running the MCP Server in STDIO mode
```bash
uv run src/mcp_server_dash.py
```

Authenticate via tools: call `dash_get_auth_url`, then `dash_authenticate` with the code. The access token is securely stored in your system's keyring (macOS Keychain, Windows Credential Manager, or Linux Secret Service).

### Token Management

Tokens are stored securely in your system keyring under the service name `mcp-server-dash` or in `~/.mcp-server-dash/dropbox_token.json`

To clear a stored token, use:

```
uv run src/mcp_server_dash.py --clear-token
```

### Common MCP Server Configuration

For most MCP clients, including Claude and Cursor, you need to insert the below JSON 
configuration into a specific configuration file. See the specific instructions for 
Claude and Cursor below.

❗ **Important:** Update the configuration below with the path to your installation and with your `APP_KEY`.

MCP Server Configuration:

```json
{
  "mcpServers": {
    "Dropbox Dash Search": {
      "command": "uv",
      "args": [
          "--directory",
          "/path/to/mcp-server-dash/",
          "run",
          "src/mcp_server_dash.py"
      ],
      "env": {
        "APP_KEY": "your_dropbox_app_key"
      }
    }
  }
}
```

**Security Note:** For better security, consider using environment variables or a `.env` file with restrictive permissions (excluded from version control) instead of placing credentials directly in the MCP config file.

### Using Claude as the Client
- Open `Claude Desktop → Settings → Developer → Local MCP Servers → Edit Config`
- Add the JSON MCP Server configuration shown above.
- Restart Claude Desktop after saving the config.

### Using Cursor as the Client

- Press `Cmd+Shift+P` (macOS) or `Ctrl+Shift+P` (Windows) to open the Command Palette
- Type "View: Open MCP Settings"
- Add the JSON MCP Server Configuration to the `mcp.json` file as instructed.

### Using Goose as the Client

- Select `Extensions → Add custom extension`
- Fill out the form:
  - **Extension Name**: Dropbox Dash Search
  - **Type**: STDIO
  - **Description**: Provide company context to your workflows
  - **Command**: `uv --directory /path/to/mcp-server-dash/ run src/mcp_server_dash.py`
  - **Environment**:
    - `APP_KEY`: Your Dropbox Client ID
- Click `Add Extension`


## Development 

Install dev tools (ruff, black, mypy, pytest, coverage) using uv:

```bash
uv pip install -e ".[dev]"
```

### Lint, Format, Type-check

Run checks (via uv):

```bash
# Lint (imports, style, bugbear, etc.)
uv run ruff check .

# Format (apply changes)
uv run black .

# Type-check
uv run mypy src
```

Tip: use `uv run ruff format .` (or `uv run black .`) to auto-format, and `uv run ruff check --fix .` to apply safe autofixes.

### Testing & Coverage

Run the test suite (quiet mode with coverage summary) using uv:

```bash
uv run pytest
# or explicitly with coverage flags
uv run pytest -q --cov=src --cov-report=term-missing
```

### Debugging
You can inspect and debug the server with the Model Context Protocol Inspector:

```bash
npx @modelcontextprotocol/inspector uv run src/mcp_server_dash.py
```

Ensure `APP_KEY` is set in your environment or `.env` before running the inspector.

## License

Apache License 2.0

Copyright (c) 2025 Dropbox, Inc.

See [LICENSE](LICENSE) for details.