MCP Tools
The markie-mcp server exposes 8 tools to AI assistants. Each tool calls the Markie REST API under the hood.
How it works
On startup, the MCP server calls GET /api/register to obtain a bearer token. Catalog responses are cached for 5 seconds with in-flight deduplication. If Markie is offline, tools return a friendly error instead of crashing.
| Tool | API Endpoint | Description |
|---|---|---|
| search_assets | GET /api/catalog | Search your Markie asset library. Supports full-text search plus filters for type, tags, date range, and colors. |
| get_asset_detail | GET /api/catalog | Get full metadata for a single asset by ID. |
| get_asset_thumbnail | GET /api/assets/{id}/thumbnail | Get the thumbnail image for an asset. Returns a base64-encoded JPEG so you can see the asset. |
| get_asset_file | GET /api/assets/{id}/file | Get the full file content of an asset as base64. Returns an error if the file is larger than 10 MB. |
| list_tags | GET /api/catalog | List all tags used in your asset library, sorted by frequency. |
| list_colors | GET /api/catalog | List all colors from asset color palettes, sorted by frequency. |
| get_recent | GET /api/catalog | Get the most recently saved assets. |
| get_stats | GET /api/catalog | Get statistics about your asset library: total count, breakdown by type, total size, tag count, and date range. |
search_assets
Search your Markie asset library. Supports full-text search plus filters for type, tags, date range, and colors.
GET /api/catalogParameters
| Name | Type | Required | Description |
|---|---|---|---|
| query | string | no | Full-text search query |
| tags | string[] | no | Filter assets that have ALL of these tags |
| type | AssetType | no | Filter by asset type (image, video, pdf, vector, website) |
| dateFrom | string | no | ISO date — assets saved on or after |
| dateTo | string | no | ISO date — assets saved on or before |
| colors | string[] | no | Filter by hex colors in the palette |
| limit | number | no | Max results (default 20, max 100) |
Processing
Fetches the full catalog, then applies hard filters (type, tags, dates, colors) client-side. If a query is provided, runs Fuse.js fuzzy search (threshold 0.4) against description, pageTitle, tags, sourceUrl, sourceDomain, and category.
Returns
Array of matching Asset objects.
get_asset_detail
Get full metadata for a single asset by ID.
GET /api/catalogParameters
| Name | Type | Required | Description |
|---|---|---|---|
| id | string | yes | Asset UUID |
Processing
Fetches the catalog and finds the asset by ID in memory.
Returns
Single Asset object, or an error if not found.
get_asset_thumbnail
Get the thumbnail image for an asset. Returns a base64-encoded JPEG so you can see the asset.
GET /api/assets/{id}/thumbnailParameters
| Name | Type | Required | Description |
|---|---|---|---|
| id | string | yes | Asset UUID |
Processing
Direct HTTP call — no auth required. Returns the thumbnail bytes.
Returns
MCP image content block (base64 JPEG, mimeType: image/jpeg).
get_asset_file
Get the full file content of an asset as base64. Returns an error if the file is larger than 10 MB.
GET /api/assets/{id}/fileParameters
| Name | Type | Required | Description |
|---|---|---|---|
| id | string | yes | Asset UUID |
Processing
Direct HTTP call — no auth required. Validates file size is under 10 MB before encoding.
Returns
JSON object with base64 (encoded content), mimeType (from Content-Type header), and size (bytes).
list_colors
List all colors from asset color palettes, sorted by frequency.
GET /api/catalogProcessing
Fetches the catalog, aggregates all colorPalette entries (lowercased), counts occurrences, and sorts by frequency.
Returns
Array of { hex: string, count: number } objects.
get_recent
Get the most recently saved assets.
GET /api/catalogParameters
| Name | Type | Required | Description |
|---|---|---|---|
| n | number | no | Number of assets to return (default 10, max 50) |
Processing
Fetches the catalog, sorts by savedAt descending, returns the first n assets.
Returns
Array of Asset objects (up to n items).
get_stats
Get statistics about your asset library: total count, breakdown by type, total size, tag count, and date range.
GET /api/catalogProcessing
Fetches the catalog and computes: total assets, count per type, total size (formatted), unique tag count, AI-enriched count, and oldest/newest dates.
Returns
JSON object with totalAssets, byType, totalSizeBytes, totalSizeFormatted, uniqueTags, aiEnrichedAssets, and dateRange.
Install
npm install -g @vitgranen/markie-mcp
Then add it to your AI assistant's MCP config. See the MCP setup page for configuration details.