MCP Server Overview

Statuz includes a built-in Model Context Protocol (MCP) server that enables AI assistants like Claude, Cursor, and Zed to manage your social media posts, schedules, and accounts directly from your editor.

What is MCP?

The Model Context Protocol is an open standard for connecting AI assistants to external tools and data sources. With Statuz's MCP server, your AI assistant can:

• 📝 Create and schedule posts via natural language
• 📅 Query and manage your content calendar
• 👥 Add and configure social media accounts
• ✏️ Edit scheduled posts without leaving your editor
• ⚙️ Control app settings programmatically

Why Use MCP?

Natural Language Control

Instead of remembering URL scheme syntax or API endpoints, just ask:

"Schedule a post about our new feature for tomorrow at 2pm"
"Show me all queued posts for next week"
"Edit the post scheduled for Monday to add a hashtag"

Editor Integration

Work seamlessly in your development environment:

• Cursor - Chat with Claude to manage posts while coding
• Claude Desktop - Full-featured AI assistant with Statuz integration
• Zed - Fast, lightweight editor with AI capabilities

No API Keys Required

The MCP server runs locally on your machine. No API keys, no external services, no network calls—just direct communication between your AI assistant and Statuz.

Premium Feature

MCP Server requires a valid Statuz license. Learn about pricing

Quick Start

1. Enable MCP Server

1. Open Statuz
2. Go to Settings → MCP Server
3. Toggle Enable MCP Server to ON
4. Copy the command path shown (usually /Applications/Statuz.app/Contents/MacOS/Statuz)

2. Configure Your AI Editor

Choose your editor:

Cursor

Add to ~/.cursor/config.json or via Settings → MCP:

{
  "mcpServers": {
    "statuz": {
      "command": "/Applications/Statuz.app/Contents/MacOS/Statuz",
      "args": ["--mcp-stdio"]
    }
  }
}

Claude Desktop

Add to ~/Library/Application Support/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "statuz": {
      "command": "/Applications/Statuz.app/Contents/MacOS/Statuz",
      "args": ["--mcp-stdio"]
    }
  }
}

Zed

Add to ~/.config/zed/settings.json:

{
  "context_servers": {
    "statuz": {
      "command": "/Applications/Statuz.app/Contents/MacOS/Statuz",
      "args": ["--mcp-stdio"]
    }
  }
}

💡 Debugging: Append --mcp-debug to the args array (or set STATUZ_MCP_DEBUG=1) to mirror every JSON-RPC message. If you prefer, you can omit the CLI flag entirely and run Statuz with STATUZ_MCP_STDIO=1 in your launch script.

3. Verify Connection

1. Restart your AI editor
2. In the AI chat, ask: "Can you list my Statuz accounts?"
3. The assistant should use the accounts_list tool and show your accounts

Available Tools

The MCP server exposes 18 tools plus two data resources for comprehensive Statuz control:

Composition & Publishing

Schedule Management

Calendar

Account Management

Settings

Other

Resources

View detailed tool reference →

MCP Resources

Statuz publishes high-level datasets you can read without making multiple tool calls:

• statuz:///accounts – Connected account metadata (id, platform, username, nickname, enabled/default flags, createdAt)
• statuz:///scheduled – Scheduled post data equivalent to scheduled_list({}), including content, media metadata, account IDs, platform modes, and share settings

Use resources_list to discover available URIs, then pass one to resources_read to fetch the JSON payload. Resource access still requires the MCP server toggle to be enabled; otherwise requests fail with error code 1000.

Example Conversations

Schedule a Post

You: "Schedule a post about our new release for tomorrow at 2pm EST"

AI: Uses schedule tool with:

{
  "text": "Excited to announce our new release! 🚀",
  "date": "2025-01-21T14:00:00",
  "timezone": "America/New_York",
  "status": "queued"
}

Query Scheduled Posts

You: "Show me all posts scheduled for next week"

AI: Uses scheduled_list tool with:

{
  "dateFrom": "2025-01-20T00:00:00Z",
  "dateTo": "2025-01-27T00:00:00Z",
  "sortBy": "date"
}

Edit a Scheduled Post

You: "Add '#feature' to the post scheduled for Monday"

AI:

1. Uses scheduled_list to find Monday's post
2. Uses scheduled_edit to update the text
3. Confirms the change

Add Account

You: "Add my Mastodon account on fosstodon.org"

AI: Uses accounts_add tool with:

{
  "platform": "mastodon",
  "instance": "fosstodon.org",
  "autoConnect": true
}

List Accounts

You: "What accounts do I have connected?"

AI: Uses accounts_list tool and shows a formatted list of your accounts with platform, username, and status.

Key Features

Stealth Mode by Default

All MCP operations default to stealth mode—changes happen without interrupting UI dialogs. Perfect for automation workflows.

Multi-Platform Support

Works with X (Twitter), BlueSky, and Mastodon simultaneously. Specify platforms per post or use your configured defaults.

Advanced Filtering

Query scheduled posts by:

• Status (draft, queued, published, failed)
• Date range
• Platform
• Text content
• Media presence
• Account

Thread Operations

Edit multi-post threads with granular operations:

• Append posts
• Insert at specific positions
• Replace individual posts
• Delete posts

Secure by Design

The MCP server:

• ✅ Runs locally on your machine
• ✅ Uses stdio (no network exposure)
• ✅ Cannot access authentication tokens
• ✅ Respects macOS sandbox restrictions
• ❌ No external API calls
• ❌ No data leaves your device

Best Practices

1. Use Natural Language

Let the AI handle tool syntax. Just describe what you want:

❌ "Call scheduled_list with dateFrom=2025-01-20"
✅ "Show me posts scheduled for tomorrow"

2. Verify Before Publishing

Use status: "draft" for posts that need review:

"Schedule a draft post for Friday at 3pm"

3. Check Status Before Editing

Published posts cannot be edited. The AI will check status automatically when you ask to edit posts.

4. Use Specific Time References

Be clear about timezones:

❌ "Schedule for 2pm"
✅ "Schedule for 2pm EST"
✅ "Schedule for 2pm Pacific time"

5. Batch Operations

The AI can perform multiple operations in one conversation:

"Schedule these three posts for tomorrow:
1. Morning update at 9am
2. Afternoon check-in at 2pm  
3. Evening wrap-up at 6pm"

Troubleshooting

MCP Server Won't Start

Problem: AI assistant can't connect to Statuz

Solutions:

1. Check Settings → MCP Server is enabled
2. Verify app path: /Applications/Statuz.app
3. Restart your AI editor completely
4. Check Console.app for "MCP" error messages
5. Ensure you have a valid Statuz license

Tool Calls Failing

Problem: AI reports tool errors

Solutions:

1. Enable MCP debug logging in Statuz settings
2. Check if post IDs are valid (use scheduled_list)
3. Verify you're not editing published posts
4. Ensure required parameters are provided

Media Not Attaching

Problem: Files don't attach to posts

Solutions:

1. Use absolute file paths: /Users/me/Desktop/image.png
2. Or use remote URLs: https://example.com/image.jpg
3. Check file exists and is readable
4. Verify format is supported (PNG, JPG, MP4, MOV)
5. Statuz may prompt for folder access on first use

Security & Privacy

What the MCP Server Can Access

✅ Can:

• Read and modify scheduled posts
• Read account metadata (usernames, nicknames)
• Change app settings
• Open UI components

❌ Cannot:

• Access authentication tokens
• Read DMs or private data
• Perform actions outside Statuz
• Access files without permission

Authentication

OAuth credentials are managed exclusively through Statuz's secure UI. The MCP server cannot:

• Read or export tokens
• Modify OAuth credentials
• Bypass security models

Local-Only Operation

The MCP server:

• Runs entirely on your Mac
• Uses stdio (standard input/output)
• No network requests
• No external services
• No data leaves your device

Platform Support

The MCP server supports all Statuz platforms:

Next Steps

• MCP Tools Reference - Detailed tool documentation
• Automation Guide - Workflow ideas that mix MCP and URL scheme
• URL Scheme API - Alternative automation method

Support

Questions about the MCP server?

• 📧 Email: support@statuz.app
• 💬 Discord Community
• 📚 GitHub Discussions