MCP Tools Reference: Complete API documentation Complete reference documentation for all tools exposed by the Statuz MCP server. Use these tools through your AI assistant for natural language control of Statuz. Composition & Publishing compose Open the Statuz composer with pre-filled content. Parameters: NameTypeRequiredDescription textstringNoPost content to prefill threadbooleanNoEnable thread mode autosplitbooleanNoAuto-split long posts mediastring[]NoLocal file paths or remote URLs filesstring[]NoAlias for media when providing raw file paths quotestringNoURL of post to quote platformsstring[]NoTarget platforms: x, bluesky, mastodon Example Usage: "Open composer with text 'Hello World' and attach ~/Desktop/image.png" AI Tool Call: { "text": "Hello World", "media": ["/Users/me/Desktop/image.png"] } schedule Schedule a post for future publication. Parameters: NameTypeRequiredDescription textstringNoPost content (optional when you want a blank draft) datestring (ISO8601)NoSchedule date/time (defaults to 1h from now with status: queued) timezonestringNoTimezone (IANA format) platformsstring[]NoTarget platforms statusstringNodraft or queued (default: draft) threadbooleanNoPost as thread autosplitbooleanNoAuto-split long posts mediastring[]NoLocal file paths or remote URLs filesstring[]NoAlias for media when passing raw file paths quotestringNoURL of post to quote postingModestringNodefaults, allEnabled, or specific xModestringNoX-specific posting mode blueskyModestringNoBlueSky-specific posting mode mastodonModestringNoMastodon-specific posting mode xAccountsstring[]NoX account identifiers blueskyAccountsstring[]NoBlueSky account identifiers mastodonAccountsstring[]NoMastodon account identifiers xShareWithFollowersstringNoX follower visibility stealthModebooleanNoSchedule without UI (default: true for MCP calls) Example Usage: "Schedule a post saying 'Big announcement tomorrow!' for tomorrow at 2pm EST" AI Tool Call: { "text": "Big announcement tomorrow!", "date": "2025-01-21T14:00:00", "timezone": "America/New_York", "status": "queued", "platforms": ["x", "bluesky"] } Schedule Management scheduled_list Query and filter scheduled posts. Parameters: NameTypeRequiredDescription statusstring or string[]NoFilter by status: draft, queued, processing, published, failed platformsstring[]NoFilter by platforms dateFromstring (ISO8601)NoStart date range dateTostring (ISO8601)NoEnd date range idstring or string[]NoFilter by post ID(s) hasMediabooleanNoFilter posts with media textContainsstringNoSearch text content postingModestringNoFilter by posting mode accountIdstring or string[]NoFilter by account ID(s) includeContentbooleanNoInclude full content (default: true) includeAccountsbooleanNoInclude account details (default: true) includeErrorbooleanNoInclude error messages (default: false) includeSharebooleanNoInclude share settings (default: false) sortBystringNoSort field: date/scheduledDate, createdAt, or status sortOrderstringNoasc or desc (default: asc) offsetintegerNoPagination offset (default: 0) limitintegerNoMax results to return (default: all matching posts) Example Usage: "Show me all queued posts for next week" AI Tool Call: { "status": "queued", "dateFrom": "2025-01-20T00:00:00Z", "dateTo": "2025-01-27T00:00:00Z", "sortBy": "date", "limit": 50 } scheduled_edit Edit an existing scheduled post. Important: Published posts cannot be edited. Only draft, queued, processing, or failed posts. Parameters: NameTypeRequiredDescription idstringYesPost UUID textstringNoNew text content (single posts) threadstring[]NoReplace entire thread threadOpsobject[]NoGranular thread operations datestring (ISO8601)NoNew schedule date/time timezonestringNoNew timezone platformsstring[]NoNew target platforms statusstringNoNew status: draft or queued only accountsstring or objectNoAccount selection autosplitbooleanNoAuto-split long posts mediastring[]NoNew local file paths or remote URLs filesstring[]NoAlias for media when supplying raw file paths stealthModebooleanNoEdit without UI (default: true) Thread Operations: Each operation object has: • op (string): insert, replace, delete, or append • index (number): Position for insert/replace/delete • text (string): Content for insert/replace/append Example Usage: "Add '#launch' to the post scheduled for Monday" AI Tool Call: { "id": "550e8400-e29b-41d4-a716-446655440000", "text": "Exciting announcement coming soon! 🚀 #launch" } scheduled_delete Delete a scheduled post permanently. Parameters: NameTypeRequiredDescription idstringYesPost UUID stealthModebooleanNoDelete without confirmation (default: true) Example Usage: "Delete the post scheduled for Friday" AI Tool Call: { "id": "550e8400-e29b-41d4-a716-446655440000", "stealthMode": true } Calendar Tools calendar_open Open the Statuz calendar view. Parameters: NameTypeRequiredDescription viewstringNoView type: day, week, month, year datestring (ISO8601)NoNavigate to specific date statusstringNoReserved for future use (currently ignored by the UI) Example Usage: "Show me the calendar in week view" AI Tool Call: { "view": "week" } Account Management accounts_list List all connected social media accounts. Parameters: None Returns: Array of account objects with platform, username, nickname, enabled status, and default flag. Note: Does not return authentication tokens or secrets. Example Usage: "What accounts do I have connected?" accounts_add Open account connection flow to add a new social media account. Parameters: NameTypeRequiredDescription platformstringYesx, bluesky, or mastodon instancestringNoMastodon instance URL (default: mastodon.social) autoConnectbooleanNoAuto-trigger OAuth (default: true) Example Usage: "Add my Mastodon account on fosstodon.org" AI Tool Call: { "platform": "mastodon", "instance": "fosstodon.org", "autoConnect": true } accounts_remove Disconnect and remove a social media account. Parameters: NameTypeRequiredDescription platformstringYesPlatform identifier idstringOne of*Account ID namestringOne of*Account username/handle nicknamestringOne of*Account nickname *Provide at least one of id, name, or nickname. Example Usage: "Remove my X account @johndoe" AI Tool Call: { "platform": "x", "name": "johndoe" } accounts_edit Edit account settings (nickname, enabled status). Note: Credentials cannot be modified for security. Parameters: NameTypeRequiredDescription platformstringYesPlatform identifier idstringOne of*Account identifier namestringOne of*Account identifier nicknamestringOne of*Account identifier setNicknamestringNoNew nickname to set setEnabledbooleanNoEnable/disable account *Provide at least one of id, name, or nickname. Example Usage: "Rename my X account to 'Work Twitter'" AI Tool Call: { "platform": "x", "name": "johndoe", "setNickname": "Work Twitter" } accounts_setDefault Set which account should be the default for a platform. Parameters: NameTypeRequiredDescription platformstringYesPlatform identifier idstringOne of*Account identifier namestringOne of*Account identifier nicknamestringOne of*Account identifier *Provide at least one of id, name, or nickname. Example Usage: "Make my personal BlueSky account the default" AI Tool Call: { "platform": "bluesky", "nickname": "Personal Account" } Settings Tools settings_open Open Statuz settings/preferences window. Parameters: NameTypeRequiredDescription sectionstringNoSection: general, composer, social, bluesky, mastodon, x, shortcuts, data, ai Example Usage: "Open the account settings" AI Tool Call: { "section": "social" } settings_platform Enable or disable entire platforms globally. Parameters: NameTypeRequiredDescription platformstringYesx, bluesky, or mastodon set-enabledbooleanYesEnable/disable platform Example Usage: "Disable the Mastodon platform" AI Tool Call: { "platform": "mastodon", "set-enabled": false } settings_list_platforms List all platforms and their enabled/disabled status. Parameters: None Returns: Array of platform objects with enabled status. Example Usage: "Which platforms are enabled?" Other Tools open Bring Statuz to foreground. Parameters: None Example Usage: "Open Statuz" license_open Open license management interface. Parameters: NameTypeRequiredDescription actionstringNoview, activate/register, verify, refresh, purchase/buy Example Usage: "Open license settings" AI Tool Call: { "action": "view" } Resource Tools resources_list List all MCP resources exposed by Statuz. Parameters: None Returns: Array of resource descriptors with uri and metadata. Example Usage: "What MCP resources are available?" resources_read Read the data for a specific MCP resource URI. Parameters: NameTypeRequiredDescription uristringYesResource URI returned by resources_list (e.g., statuz:///accounts) Example Usage: "Fetch the MCP scheduled posts resource" AI Tool Call: { "uri": "statuz:///scheduled" } Note: Statuz currently exposes statuz:///accounts and statuz:///scheduled. Both respect the same permission checks as their corresponding tools and require the MCP toggle to be enabled. Common Patterns Schedule a Simple Post You: "Schedule a post saying 'Hello World' for tomorrow at 2pm" AI uses: schedule({ text: "Hello World", date: "2025-01-21T14:00:00", timezone: "America/New_York", status: "queued" }) Query and Edit Posts You: "Find the post scheduled for Monday and add #announcement" AI: 1. scheduled_list({ dateFrom: "2025-01-20", dateTo: "2025-01-21" }) 2. scheduled_edit({ id: "found-id", text: "Original text #announcement" }) Batch Schedule Posts You: "Schedule these posts for the week: - Monday 9am: Morning motivation - Wednesday 2pm: Mid-week check-in - Friday 4pm: Weekend vibes" AI uses: schedule() three times with appropriate dates Account Context Switching You: "Switch to my work accounts" AI: 1. accounts_list() to find work accounts 2. accounts_setDefault() for each platform with work account Best Practices 1. Use Natural Language Let the AI interpret your intent: ✅ "Schedule a post about our launch for tomorrow afternoon" ❌ "Call schedule tool with text parameter and date 2025-01-21T14:00:00Z" 2. Check Before Editing The AI automatically checks post status before editing: posts = scheduled_list(id="some-id") if posts[0].status == "published": # Cannot edit - inform user else: # Safe to edit 3. Use Stealth Mode For automation, stealth mode prevents UI interruptions: { "id": "post-id", "text": "Updated content", "stealthMode": true } 4. Leverage Filtering Use advanced filters for precise queries: { "status": ["queued", "draft"], "dateFrom": "2025-01-20", "platforms": ["x"], "textContains": "announcement" } Error Handling The AI assistant will receive error messages for: • Invalid post ID - Post not found • Published post edit - Cannot edit published posts • Invalid account - Account not found or invalid identifier • Invalid date - Date format or past date issues • Network errors - Remote media download failures Security Notes What Can Be Accessed ✅ Can: • Read and modify scheduled posts • Read account metadata • Change app settings ❌ Cannot: • Access authentication tokens • Read private messages • Bypass security restrictions Local-Only Operation • Runs entirely on your Mac • Uses stdio (no network) • No data leaves your device • Respects macOS sandbox Related Documentation • MCP Overview (/docs/mcp-overview) - Getting started with MCP • Automation Guide (/docs/automation-guide) - Workflow ideas that mix MCP and URL schemes • URL Scheme API (/docs/url-scheme-overview) - Alternative automation Support Need help with MCP tools? • 📧 Email: support@statuz.gg (mailto:support@statuz.gg) • 💬 Discord Community (https://discord.gg/statuz) • 📚 Full Documentation (/docs) Try Statuz today, it's free. Download for macOS (/download)