Mediagraph MCP Server

An MCP (Model Context Protocol) server that provides AI assistants with access to the Mediagraph digital asset management platform.

Features

• OAuth Authentication: Secure authorization with PKCE support
• Asset Management: Search, view, and update digital assets
• Organization Tools: Work with collections, lightboxes, and folders
• Tagging: Add and manage asset tags
• Sharing: Create share links for assets and collections
• Bulk Operations: Perform batch updates on multiple assets

Installation

npm install -g @mediagraph/mcp

Or run directly with npx:

npx @mediagraph/mcp

Quick Start with Claude Desktop

The easiest way to get started is with Claude Desktop.

Option A: One-Click Install (Recommended)

1. Download the latest mediagraph-mcp.mcpb bundle from GitHub Releases
2. Open the file — it will automatically configure Claude Desktop
3. Authorize with your Mediagraph account when prompted

Option B: Manual Configuration

1. Authorize

npx @mediagraph/mcp authorize

This will open a browser window for you to log in and authorize the MCP server with your Mediagraph account.

2. Configure Claude Desktop

Add the following to your Claude Desktop configuration file:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "mediagraph": {
      "command": "npx",
      "args": ["@mediagraph/mcp"]
    }
  }
}

3. Restart Claude Desktop

Start Using

Once configured, you can ask Claude to:

• "Search for images tagged 'sunset'"
• "Show me the details of asset ABC123"
• "Add tags 'nature' and 'landscape' to this asset"
• "Create a new collection called 'Project Photos'"
• "Find all videos uploaded this week"

Visual Asset Browser

In Claude Desktop, you can ask Claude to visually search your assets using the search_assets_visual tool. This opens an interactive gallery directly in the chat with:

• Thumbnail grid — browse search results visually with hover previews
• Asset detail panel — click any asset to view a full preview with file info, EXIF/IPTC metadata, and tags
• Inline editing — edit title, description, alt text, caption, credit, and copyright without leaving Claude
• Ratings — rate assets with a star rating
• Tagging — add and remove tags from assets
• Downloads — download assets in multiple sizes (small, medium, full, original) with optional watermarking
• Bulk downloads — select multiple assets and download them at once
• Pagination — navigate through large result sets

Try asking Claude: "Visually show me all images tagged 'landscape'"

Available Tools

| Tool | Description | |------|-------------| | whoami | Get current user and organization info | | search_assets | Search assets with filters (tags, dates, ratings, etc.) | | search_assets_visual | Search assets and display results in an interactive visual gallery | | get_asset | Get detailed asset information | | update_asset | Update asset metadata (title, description, etc.) | | add_tags | Add tags to an asset | | download_asset | Get a download URL for an asset | | list_collections | List all collections | | get_collection | Get collection details | | create_collection | Create a new collection | | add_to_collection | Add an asset to a collection | | list_lightboxes | List all lightboxes | | get_lightbox | Get lightbox details | | create_lightbox | Create a new lightbox | | add_to_lightbox | Add an asset to a lightbox | | list_storage_folders | List storage folders | | list_tags | List available tags | | create_share_link | Create a share link | | bulk_update | Bulk operations on multiple assets |

Available Resources

The server provides MCP resources for direct access to Mediagraph data:

• mediagraph://asset/{id} - Asset details
• mediagraph://collection/{id} - Collection with assets
• mediagraph://lightbox/{id} - Lightbox with assets
• mediagraph://search?q={query} - Search results

CLI Commands

# Authorize with Mediagraph
npx @mediagraph/mcp authorize

# Check authentication status
npx @mediagraph/mcp status

# Log out and revoke tokens
npx @mediagraph/mcp logout

# Show help
npx @mediagraph/mcp help

Environment Variables

All environment variables are optional. The default configuration works out of the box.

| Variable | Default | Description | |----------|---------|-------------| | MEDIAGRAPH_CLIENT_ID | (built-in) | OAuth client ID (override for custom apps) | | MEDIAGRAPH_CLIENT_SECRET | - | OAuth client secret (for confidential clients) | | MEDIAGRAPH_API_URL | https://api.mediagraph.io | API base URL | | MEDIAGRAPH_OAUTH_URL | https://mediagraph.io | OAuth server URL | | MEDIAGRAPH_REDIRECT_PORT | 52584 | Local callback port for OAuth |

Security

• Tokens are stored encrypted in ~/.mediagraph/tokens.enc
• PKCE is used for OAuth to prevent authorization code interception
• Access tokens are automatically refreshed before expiration
• No sensitive data is logged or exposed

Development

# Clone the repository
git clone https://github.com/mediagraph/mediagraph-mcp.git
cd mediagraph-mcp

# Install dependencies
npm install

# Build
npm run build

# Run in development mode
npm run dev

Testing with MCP Inspector

# Build the project
npm run build

# Run with inspector
npx @modelcontextprotocol/inspector node dist/index.js

License

MIT License - see LICENSE for details.

Support

• API Documentation
• GitHub Issues