MCP Tools Reference

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:

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:

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:

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:

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:

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:

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:

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:

*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:

*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:

*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:

Example Usage:

"Open the account settings"

AI Tool Call:

{
  "section": "social"
}

settings_platform

Enable or disable entire platforms globally.

Parameters:

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:

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:

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 - Getting started with MCP
• Automation Guide - Workflow ideas that mix MCP and URL schemes
• URL Scheme API - Alternative automation

Support

Need help with MCP tools?

• 📧 Email: support@statuz.app
• 💬 Discord Community
• 📚 Full Documentation