Postiz Media Manager - MCP Server

MCP (Model Context Protocol) Server media Postiz

• ** Media IDs ** - media draft, scheduled, queued
• ** Orphan Media** - media
• ** Media ** - dry-run mode
• ** Media** - media , , orphan

mcp-postiz/
 src/
    types.ts          # TypeScript type definitions
    config.ts         # Configuration management
    postizClient.ts   # Postiz API client (PLACEHOLDER endpoints)
    mediaService.ts   # Business logic for media management
    mcpServer.ts      # MCP server implementation
 package.json
 tsconfig.json
 .env.example
 README.md

1. Clone dependencies

npm install

2. Environment Variables

.env .env.example:

cp .env.example .env

.env:

# Base URL  Postiz API
POSTIZ_BASE_URL=https://api.postiz.app

# API Token  authentication
POSTIZ_API_TOKEN=your_actual_api_token_here

# Log level (debug, info, warn, error)
LOG_LEVEL=info

3. API Endpoints (!)

** :** src/postizClient.ts PLACEHOLDER endpoints

endpoints Postiz API :

• GET /v1/posts endpoint
• GET /v1/media endpoint media
• DELETE /v1/media/:id endpoint media

API Postiz src/postizClient.ts

4. Media Field Extraction (!)

src/mediaService.ts extractMediaIds() media IDs:

//  API 
- post.mediaIds
- post.files
- post.attachments
- post.media

Postiz API

5. Build

npm run build

6. MCP Server

npm start

MCP Tools

1. postiz_list_future_protected_media_ids

media IDs ()

Input:

{
  "statuses": ["draft", "scheduled", "queued"]  // Optional
}

Output:

{
  "protectedMediaIds": ["media-id-1", "media-id-2", "media-id-3"],
  "count": 3
}

2. postiz_list_all_media

media

Input:

{
  "limit": 100  // Optional
}

Output:

{
  "items": [
    {
      "id": "media-id-1",
      "url": "https://example.com/media1.jpg",
      "createdAt": "2025-01-01T00:00:00Z",
      "deleted": false,
      "deletedAt": null
    }
  ],
  "total": 150,
  "returned": 100
}

3. postiz_find_orphan_media

media (orphan media)

Input:

{
  "limit": 50  // Optional
}

Output:

{
  "items": [
    {
      "id": "orphan-media-1",
      "url": "https://example.com/orphan1.jpg",
      "createdAt": "2024-12-01T00:00:00Z"
    }
  ],
  "totalCandidates": 25
}

4. postiz_cleanup_orphan_media

orphan media ( dry-run mode)

Input:

{
  "dryRun": true,   // true = , false =  (default: false)
  "limit": 10       // Optional: 
}

Output:

{
  "totalCandidates": 10,
  "deletedCount": 8,
  "failedCount": 2,
  "deletedIds": ["media-1", "media-2", "media-3"],
  "failedIds": [
    {
      "id": "media-4",
      "reason": "Permission denied"
    }
  ]
}

5. postiz_get_media_stats

media

Input:

{}

Output:

{
  "totalMedia": 1000,
  "protectedMedia": 750,
  "orphanMedia": 250
}

media :

1. :

   Tool: postiz_get_media_stats
   

2. ** dry-run:**

   Tool: postiz_cleanup_orphan_media
   Input: { "dryRun": true, "limit": 10 }
   

3. :

   Tool: postiz_find_orphan_media
   Input: { "limit": 10 }
   

4. ** ():**

   Tool: postiz_cleanup_orphan_media
   Input: { "dryRun": false, "limit": 10 }
   

5. ---

Logic

Orphan Media ?

Media "orphan" () :

1. ** ** :

   • draft ()
   • scheduled ()
   • queued ()

2. **** (deleted = false deletedAt = null)

?

**** :

• Media scheduled ****
• Media ****

Config MCP Client

server MCP client configuration ( Claude Desktop):

{
  "mcpServers": {
    "postiz-media-manager": {
      "command": "node",
      "args": ["/path/to/mcp-postiz/dist/mcpServer.js"],
      "env": {
        "POSTIZ_BASE_URL": "https://api.postiz.app",
        "POSTIZ_API_TOKEN": "your_token_here"
      }
    }
  }
}

Development

Build Watch Mode

# Build 
npm run build

# Watch mode (auto-rebuild on change)
npm run dev

# Clean build artifacts
npm run clean

1. TypeScript compile :

npm run build

1. server:

npm start

1. MCP client

Error Handling

• API call try-catch error logging
• media failedIds
• Axios interceptor HTTP errors

:

1. ** dryRun: true **
2. ** cleanup **
3. ** endpoint URLs ** - code placeholder
4. ** media API** - extractMediaIds()
5. ** limit **

License

MIT

TypeScript + MCP SDK media Postiz