Ayrshare MCP Server

A production-ready FastMCP server providing complete Ayrshare API coverage with 75+ MCP tools across 15 API categories. Post to 13+ platforms including Facebook, Instagram, Twitter/X, LinkedIn, TikTok, YouTube, Pinterest, Reddit, Snapchat, Telegram, Threads, Bluesky, and Google Business Profile through a unified interface.

Features: Multi-user SaaS management, AI content generation, advanced automation, complete media library, brand management, and comprehensive validation tools.

Features

Core Publishing

• Multi-Platform Publishing: Post to 13+ social networks simultaneously
• Scheduling: Schedule posts for future publication with ISO 8601 date format
• Bulk Operations: Create multiple posts in a single operation
• Auto-Hashtags: Automatic hashtag generation (1-10 hashtags)
• Evergreen Content: Auto-reposting for timeless content (1-10 reposts)
• First Comment: Automatic first comment on posts
• Approval Workflows: Submit posts for approval before publication

Engagement Management

• Comments API: Read, add, reply to, and delete comments on posts
• Direct Messages: Send DMs, manage conversations, mark as read (Business Plan)
• Google Business Reviews: Get reviews, respond, manage review responses

Analytics & Insights

• Post Analytics: Engagement metrics (likes, shares, comments, impressions)
• Social Analytics: Aggregate analytics across multiple platforms
• Profile Analytics: Follower counts, demographics, and audience insights
• Link Analytics: Track performance of shortened URLs

Multi-User & SaaS (Business Plan)

• Profiles API: Complete multi-user profile management for SaaS platforms
• Team Management: Create team profiles with email-based access
• Profile Filtering: Filter by connected platforms, tags, and activity
• OAuth Integration: User-managed social account linking

AI-Powered Features (Max Pack)

• Content Generation: AI-powered post text creation with tone control
• Hashtag Generation: AI-driven hashtag suggestions
• Image Captions: Automatic AI caption generation for images

Automation & Scheduling

• Auto-Schedule API: AI-powered optimal posting times
• Evergreen Content: Auto-repost for timeless content (1-10 reposts)
• Scheduled Posts Calendar: View and manage content calendar
• Auto-Repost Tracking: Track series of recurring posts

Content Discovery & Optimization

• Hashtag Discovery: Trending and relevant hashtag suggestions
• Performance Analytics: Track hashtag metrics over time
• Social Feeds: Retrieve platform-specific content feeds
• Regional Trends: Discover trending content by region

Brand Management

• Brand Profiles: Centralized brand identity management
• Brand Assets: Store logos, colors, and templates
• Consistent Branding: Apply brand guidelines across posts

Advanced Features

• Webhooks: Real-time notifications for post events (Business Plan)
• Link Shortening: Custom URL shortening with analytics (Max Pack)
• Ads Management: Complete Facebook Ads integration with targeting
• Media Library: Complete media asset management with 90-day storage
• Unsplash Integration: Access royalty-free images

Quality Assurance & Validation

• Pre-Publishing Validation: Validate posts before publishing
• Media Verification: Check media URLs and format compatibility
• Schedule Validation: Verify schedule times and timezone handling
• Error Prevention: Catch issues before they reach social platforms

Infrastructure

• Complete History API: Track all posts with advanced filtering
• User Management: Account settings and API usage limits
• Timezone Tools: List and convert between timezones
• Error Handling: Comprehensive error handling and validation

Supported Platforms

Platform	Images	Videos	Scheduling	Notes
Facebook	✅	✅	✅	Up to 63,206 characters
Instagram	✅	✅	✅	Business account required
Twitter/X	✅	✅	✅	280 character limit
LinkedIn	✅	✅	✅	Up to 3,000 characters
TikTok	❌	✅	✅	Videos only
YouTube	❌	✅	✅	Video uploads
Pinterest	✅	✅	✅	-
Reddit	✅	✅	✅	-
Snapchat	✅	✅	✅	-
Telegram	✅	✅	✅	-
Threads	✅	✅	✅	500 character limit
Bluesky	✅	❌	✅	300 character limit
Google Business Profile	✅	✅	✅	Formerly Google My Business

Prerequisites

• Python 3.10 or higher
• Ayrshare API account (free tier available)
• API key from Ayrshare dashboard
• Social media accounts connected through Ayrshare

Installation

Option 1: Using uv (Recommended)

# Clone or navigate to the project directory
cd ayrshare-mcp

# Create virtual environment
uv venv

# Activate virtual environment
source .venv/bin/activate  # On Windows: .venv\Scripts\activate

# Install dependencies
uv pip install -e .

Option 2: Using pip

# Clone or navigate to the project directory
cd ayrshare-mcp

# Create virtual environment
python -m venv .venv

# Activate virtual environment
source .venv/bin/activate  # On Windows: .venv\Scripts\activate

# Install dependencies
pip install -e .

Configuration

1. Copy environment template:

   cp .env.example .env
   

2. Get your Ayrshare API key:

   • Sign up at ayrshare.com
   • Navigate to API Key page
   • Copy your API key

3. Add API key to .env:

   AYRSHARE_API_KEY=your_actual_api_key_here
   

4. Optional: Add Profile Key (for multi-tenant scenarios):

   AYRSHARE_PROFILE_KEY=your_profile_key_here
   

5. Connect social media accounts:

   • Go to Ayrshare dashboard
   • Click "Connect Account" for each platform you want to use
   • Follow the OAuth flow to authorize each platform

Usage

Running Locally (STDIO Mode)

For use with Claude Desktop or other MCP clients:

fastmcp run src/server.py

Or using Python directly:

python src/server.py

Running as HTTP Server

For remote access or API integration:

python src/server.py --http

The server will start on http://localhost:8000 by default.

Testing the Server

You can test the server using FastMCP's dev mode:

fastmcp dev src/server.py

This opens an interactive interface to test all tools and resources.

Available Tools

Core Posting Tools

1. post_to_social

Publish a post immediately to multiple platforms.

{
    "post_text": "Check out our new product launch! 🚀",
    "platforms": ["facebook", "twitter", "linkedin"],
    "media_urls": ["https://example.com/image.jpg"],
    "shorten_links": true
}

2. schedule_post

Schedule a post for future publication (ISO 8601 date format).

{
    "post_text": "Happy New Year! 🎉",
    "platforms": ["facebook", "instagram"],
    "scheduled_date": "2025-01-01T00:00:00Z",
    "media_urls": ["https://example.com/celebration.jpg"]
}

3. delete_post

Delete a post from specified platforms.

{
    "post_id": "abc123",
    "platforms": ["facebook"]  # Optional: omit to delete from all
}

4. update_post

Update content of an existing scheduled or published post.

{
    "post_id": "abc123",
    "post_text": "Updated content",
    "platforms": ["facebook", "twitter"]
}

5. retry_post

Retry a failed post (useful after temporary platform issues).

{
    "post_id": "abc123"
}

6. copy_post

Copy an existing post to different platforms or reschedule.

{
    "post_id": "abc123",
    "platforms": ["linkedin", "pinterest"],
    "scheduled_date": "2024-12-26T15:00:00Z"  # Optional
}

Advanced Posting Tools

7. bulk_post

Create multiple posts in a single operation.

{
    "posts": [
        {
            "post": "First post content",
            "platforms": ["facebook", "twitter"]
        },
        {
            "post": "Second post content",
            "platforms": ["linkedin"],
            "scheduleDate": "2024-12-25T12:00:00Z"
        }
    ]
}

8. post_with_auto_hashtags

Post with automatic hashtag generation (1-10 hashtags).

{
    "post_text": "Excited to announce our new sustainable product line!",
    "platforms": ["twitter", "instagram"],
    "max_hashtags": 3,
    "position": "auto"  # or "end"
}

9. create_evergreen_post

Create auto-reposting content (1-10 reposts, minimum 2 days between).

{
    "post_text": "The best time to start is now!",
    "platforms": ["facebook", "twitter"],
    "repeat": 5,
    "days_between": 7,
    "start_date": "2024-12-25T09:00:00Z"  # Optional
}

10. post_with_first_comment

Post with automatic first comment (20-90 seconds after post).

{
    "post_text": "New blog post is live!",
    "platforms": ["facebook", "linkedin"],
    "first_comment": "Read more at our website: https://example.com/blog",
    "comment_media_urls": ["https://example.com/blog-preview.jpg"]
}

11. submit_post_for_approval

Submit post for approval before publication.

{
    "post_text": "Big announcement coming soon!",
    "platforms": ["facebook", "twitter", "linkedin"],
    "notes": "Please review for compliance",
    "scheduled_date": "2024-12-25T10:00:00Z"
}

12. approve_post

Approve a post that is awaiting approval.

{
    "post_id": "abc123"
}

Analytics Tools

13. get_post_analytics

Get engagement metrics for a specific post.

{
    "post_id": "abc123",
    "platforms": ["facebook", "twitter"]
}

Returns: Likes, shares, comments, impressions, reach, engagement rate.

14. get_social_analytics

Get aggregate analytics across multiple platforms.

{
    "platforms": ["facebook", "instagram", "twitter"]
}

15. get_profile_analytics

Get profile/account analytics including follower counts and demographics.

{
    "platforms": ["facebook", "linkedin"]  # Optional
}

Comments API Tools

16. get_post_comments

Get all comments on a specific post.

{
    "post_id": "abc123",
    "platforms": ["facebook", "instagram"]  # Optional
}

17. add_comment_to_post

Add a comment to an existing post.

{
    "post_id": "abc123",
    "comment_text": "Thanks for all the feedback!",
    "platforms": ["facebook", "linkedin"]
}

18. reply_to_comment

Reply to a specific comment.

{
    "comment_id": "comment_xyz",
    "reply_text": "Thank you for your support!",
    "platform": "facebook"
}

19. delete_post_comment

Delete a comment from a post.

{
    "comment_id": "comment_xyz",
    "platforms": ["facebook"]
}

Direct Messages API Tools (Business Plan Required)

20. send_direct_message

Send a direct message to a user.

{
    "platform": "facebook",
    "recipient_id": "user123",
    "message": "Thank you for reaching out!",
    "media_urls": ["https://example.com/response.jpg"]  # Optional
}

21. get_message_conversations

Get list of message conversations.

{
    "platform": "instagram",
    "limit": 50  # Optional
}

22. get_conversation_history

Get messages from a specific conversation.

{
    "conversation_id": "conv123",
    "platform": "facebook",
    "limit": 100  # Optional
}

23. mark_messages_as_read

Mark messages as read.

{
    "message_ids": ["msg1", "msg2", "msg3"],
    "platform": "instagram"
}

Google Business Reviews API Tools

24. get_google_business_reviews

Get reviews for Google Business Profile locations.

{
    "location_id": "loc123"  # Optional: omit for all locations
}

25. respond_to_review

Respond to a Google Business Profile review.

{
    "review_id": "review123",
    "response_text": "Thank you for your feedback!"
}

26. remove_review_response

Delete a review response.

{
    "review_id": "review123"
}

Webhooks API Tools (Business Plan Required)

27. setup_webhook_endpoint

Create a webhook subscription for post events.

{
    "url": "https://your-domain.com/webhook",
    "events": ["post.published", "post.failed", "post.scheduled"]
}

28. list_webhook_subscriptions

Get all configured webhooks.

{}

29. update_webhook_configuration

Update an existing webhook.

{
    "webhook_id": "webhook123",
    "url": "https://new-domain.com/webhook",  # Optional
    "events": ["post.published", "post.analytics"]  # Optional
}

30. remove_webhook

Delete a webhook subscription.

{
    "webhook_id": "webhook123"
}

Links API Tools (Max Pack Add-on Required)

31. shorten_url

Shorten a URL with optional custom slug.

{
    "url": "https://example.com/very/long/url/path",
    "custom_slug": "promo2024"  # Optional
}

32. get_link_analytics

Get analytics for a shortened link.

{
    "link_id": "link123"
}

Ads API Tools (Business Plan Required)

33. create_ad_from_post

Create a paid ad campaign from an existing post.

{
    "post_id": "abc123",
    "budget": 50.00,
    "duration": 7,  # days
    "targeting": {  # Optional
        "age_range": "25-45",
        "interests": ["technology", "business"]
    }
}

34. get_ad_analytics

Get performance analytics for an ad campaign.

{
    "ad_id": "ad123"
}

35. manage_ad_campaign

Update ad budget or status.

{
    "ad_id": "ad123",
    "budget": 75.00,  # Optional
    "status": "paused"  # Optional: active, paused
}

36. stop_ad_campaign

Stop and delete an ad campaign.

{
    "ad_id": "ad123"
}

Media Management Tools

37. upload_media

Upload media to Ayrshare library for reuse.

{
    "file_url": "https://example.com/product-image.jpg",
    "file_name": "summer-collection-hero.jpg"  # Optional
}

38. validate_media_url

Validate a media URL for accessibility and format.

{
    "media_url": "https://example.com/image.jpg"
}

39. get_unsplash_image

Get royalty-free image from Unsplash integration.

{
    "query": "sunset beach vacation",  # Search query
    # OR
    "image_id": "HubtZZb2fCM"  # Specific image ID
}

Platform Information

40. list_platforms

Get information about all supported platforms.

{}

Returns: Platform capabilities, character limits, and requirements.

---

Multi-User Profile Management (Business Plan)

41. create_user_profile

Create a new user profile for multi-tenant SaaS applications.

{
    "title": "Client ABC Social Account",
    "messaging_active": true,
    "team": false,
    "disable_social": ["snapchat", "tiktok"],
    "tags": ["client-abc", "premium-tier"]
}

42. list_user_profiles

List and filter all user profiles.

{
    "has_active_social_accounts": true,
    "includes_active_social_accounts": ["facebook", "instagram"],
    "action_log": true,
    "limit": 100
}

43. get_user_profile_details

Get detailed information about a specific profile.

{
    "profile_key": "PROFILE_KEY_HERE"
}

44. update_user_profile

Update profile settings and configuration.

{
    "profile_key": "PROFILE_KEY_HERE",
    "settings": {
        "messaging_active": false,
        "disable_social": ["reddit"]
    }
}

45. delete_user_profile

Delete a user profile (irreversible).

{
    "profile_key": "PROFILE_KEY_HERE"
}

---

History & Content Calendar

46. get_post_by_history_id

Get detailed information about a specific historical post.

{
    "history_id": "hist_abc123"
}

47. get_all_scheduled_posts

View your content calendar with all scheduled posts.

{}

48. get_repost_series

Track an evergreen content auto-repost series.

{
    "auto_repost_id": "repost_xyz789"
}

---

Media Library Management

49. list_all_media

List all media files in your library with pagination.

{
    "limit": 50,
    "cursor": "next_page_token"  # Optional
}

50. get_media_item_details

Get detailed information about a specific media file.

{
    "media_id": "media_abc123"
}

51. delete_media_file

Remove a media file from your library.

{
    "media_id": "media_abc123"
}

---

Automation & AI Scheduling

52. setup_auto_schedule

Configure AI-powered optimal posting times.

{
    "schedule_config": {
        "timezone": "America/New_York",
        "days": ["monday", "wednesday", "friday"],
        "times_per_day": 2
    }
}

53. get_current_auto_schedule

View current auto-schedule configuration.

{}

54. modify_auto_schedule

Update auto-schedule settings.

{
    "schedule_config": {
        "times_per_day": 3
    }
}

55. remove_auto_schedule

Disable auto-scheduling.

{}

---

Brand Management

56. create_brand_profile_config

Set up centralized brand identity.

{
    "brand_data": {
        "name": "Company Name",
        "colors": ["#FF5733", "#C70039"],
        "logo_url": "https://example.com/logo.png",
        "tone": "professional"
    }
}

57. get_brand_profile_assets

Retrieve brand assets and guidelines.

{}

58. update_brand_profile_settings

Update brand configuration.

{
    "brand_data": {
        "tone": "casual",
        "tagline": "Innovation at its best"
    }
}

---

Social Feed Retrieval

59. get_platform_feed

Get content feed from a specific platform.

{
    "platform": "instagram",
    "limit": 20
}

60. get_all_platform_feeds

Get feeds from all connected platforms.

{
    "limit": 50
}

---

AI Content Generation (Max Pack)

61. ai_generate_post_text

AI-powered post text creation.

{
    "prompt": "Write about our new product launch",
    "platform": "linkedin",
    "tone": "professional"
}

62. ai_generate_hashtags_for_content

AI-driven hashtag generation.

{
    "content": "Excited to announce our new sustainable product line!",
    "count": 5
}

63. ai_generate_image_caption

Automatic AI caption generation for images.

{
    "image_url": "https://example.com/product.jpg",
    "style": "engaging"
}

---

Hashtag Discovery & Analytics

64. suggest_relevant_hashtags

Get relevant hashtag suggestions for your content.

{
    "content": "Check out our latest tech innovation",
    "platform": "twitter"
}

65. get_trending_platform_hashtags

Discover trending hashtags by platform and region.

{
    "platform": "instagram",
    "region": "US"
}

66. analyze_hashtag_metrics

Track hashtag performance over time.

{
    "hashtag": "#TechInnovation",
    "time_range": "30days"
}

---

Account Management

67. get_account_information

Get your account details and status.

{}

68. update_account_settings

Update account preferences.

{
    "settings": {
        "email_notifications": true,
        "timezone": "America/Los_Angeles"
    }
}

69. get_api_usage_limits

Monitor API usage and rate limits.

{}

---

Utility Functions

70. verify_media_accessibility

Pre-check media URL accessibility and format.

{
    "url": "https://example.com/video.mp4"
}

71. list_available_timezones

Get list of supported timezones for scheduling.

{}

72. convert_time_between_timezones

Convert times between timezones.

{
    "time": "2024-12-25T10:00:00",
    "from_tz": "America/New_York",
    "to_tz": "Europe/London"
}

---

Pre-Publishing Validation

73. validate_post_before_publishing

Validate post parameters before publishing.

{
    "post_data": {
        "post": "Hello world!",
        "platforms": ["facebook", "twitter"],
        "mediaUrls": ["https://example.com/image.jpg"]
    }
}

74. validate_media_for_platform

Check media compatibility for specific platforms.

{
    "media_url": "https://example.com/video.mp4",
    "platform": "instagram"
}

75. validate_schedule_datetime

Verify schedule time is valid for platforms.

{
    "schedule_date": "2024-12-25T10:00:00Z",
    "platform": "linkedin"
}

---

Available Resources

MCP Resources provide URI-based access to dynamic data that updates automatically. These are especially useful for monitoring, reporting, and real-time data access.

1. ayrshare://history

Access recent post history (last 30 days).

Returns: Formatted list of posts with status, platforms, and content.

Use Cases: Content auditing, compliance tracking, performance review

2. ayrshare://platforms

Access connected social media profiles and their connection status.

Returns: List of connected platforms with account details and status.

Use Cases: Account management, troubleshooting connection issues

3. ayrshare://analytics/dashboard/{period}

Real-time analytics dashboard with aggregated metrics across all platforms.

URI Patterns:

• ayrshare://analytics/dashboard/daily - Last 24 hours
• ayrshare://analytics/dashboard/weekly - Last 7 days
• ayrshare://analytics/dashboard/monthly - Last 30 days
• ayrshare://analytics/dashboard/quarterly - Last 90 days

Returns: Comprehensive dashboard with:

• Total posts and success rate
• Platform breakdown
• Posting consistency metrics
• Recent activity summary

Use Cases: Performance monitoring, client reporting, strategic planning

Example:

# Access monthly dashboard
dashboard = await mcp.read_resource("ayrshare://analytics/dashboard/monthly")

4. ayrshare://calendar/{year}/{month}

Content calendar view showing all scheduled posts for a specific month.

URI Patterns:

• ayrshare://calendar/2024/12 - December 2024
• ayrshare://calendar/2025/01 - January 2025

Returns: Calendar view with:

• All scheduled posts grouped by date
• Post times and platforms
• Content previews
• Total post count per day

Use Cases: Content planning, scheduling visualization, campaign coordination

Example:

# View December 2024 calendar
calendar = await mcp.read_resource("ayrshare://calendar/2024/12")

5. ayrshare://profiles/overview

Overview of all customer profiles for multi-tenant SaaS management.

Returns: Comprehensive profile summary with:

• Total active and inactive profiles
• Connected platforms per profile
• Average platforms per customer
• Individual profile details

Use Cases: Customer management, SaaS monitoring, account health tracking

Example:

# Get all customer profiles
profiles = await mcp.read_resource("ayrshare://profiles/overview")

---

Available Prompts

MCP Prompts provide templated LLM workflows for common social media tasks. These help maintain consistency and quality across content creation.

1. create_social_post

Generate platform-optimized social media content with proper formatting, hashtags, and CTAs.

Parameters:

• topic (required): Main topic or subject of the post
• platform (required): Target platform (facebook, twitter, linkedin, instagram, tiktok)
• tone: Desired tone (professional, casual, funny, inspiring, educational) - default: "professional"
• target_audience: Description of target audience - default: "general"
• call_to_action: Optional CTA to include
• include_hashtags: Whether to include hashtags - default: true

Supported Platforms:

• Twitter: 280 chars, 1-2 hashtags, punchy style
• Facebook: Story-driven, minimal hashtags, engaging questions
• LinkedIn: Professional, 3-5 hashtags, thought leadership
• Instagram: Visual-first, 10-30 hashtags, emoji support
• TikTok: Authentic, 3-5 trending hashtags, attention-grabbing

Returns: Complete prompt for LLM to generate ready-to-publish content

Example Usage:

# Generate LinkedIn post about AI
prompt = create_social_post(
    topic="The future of AI in business",
    platform="linkedin",
    tone="professional",
    target_audience="business executives",
    call_to_action="Read our full report",
    include_hashtags=True
)

2. analyze_performance

Analyze social media performance data and provide strategic insights and recommendations.

Parameters:

• post_analytics (required): JSON or text with analytics data
• time_period: Time period covered - default: "last 30 days"
• platform: Specific platform or "all platforms" - default: "all platforms"

Analysis Includes:

1. Performance Overview: Key metrics, best/worst content, benchmarks
2. Trends & Patterns: Content types, posting times, platform effectiveness
3. Audience Insights: Engagement patterns, demographics, topic resonance
4. Actionable Recommendations: Specific improvement strategies
5. Next Steps: Priority actions with expected impact

Returns: Structured prompt for comprehensive performance analysis

Example Usage:

# Analyze monthly performance
analytics_data = """
{
  "total_posts": 45,
  "engagement_rate": 3.2%,
  "reach": 125000,
  "top_platform": "linkedin"
}
"""

prompt = analyze_performance(
    post_analytics=analytics_data,
    time_period="last 30 days",
    platform="all platforms"
)

3. optimize_for_platform (Existing)

Optimize existing post content for specific platforms considering character limits and best practices.

4. generate_hashtags (Existing)

Generate relevant, platform-appropriate hashtags for post content.

5. schedule_campaign (Existing)

Plan and schedule multi-post campaigns across platforms.

---

Claude Desktop Integration

Add to your Claude Desktop configuration (claude_desktop_config.json):

STDIO Mode (Recommended)

{
  "mcpServers": {
    "ayrshare": {
      "command": "python",
      "args": ["/absolute/path/to/ayrshare-mcp/src/server.py"],
      "env": {
        "AYRSHARE_API_KEY": "your_api_key_here"
      }
    }
  }
}

HTTP Mode

{
  "mcpServers": {
    "ayrshare": {
      "url": "http://localhost:8000",
      "transport": "http"
    }
  }
}

Examples

Post to Multiple Platforms

# Immediate post
result = await post_to_social(
    post_text="Excited to announce our new feature! Learn more at example.com",
    platforms=["facebook", "twitter", "linkedin"],
    media_urls=["https://cdn.example.com/feature-image.jpg"]
)

print(f"Posted with ID: {result['post_id']}")

Schedule Future Post

# Schedule for Christmas morning
result = await schedule_post(
    post_text="Merry Christmas from our team! 🎄",
    platforms=["facebook", "instagram", "twitter"],
    scheduled_date="2024-12-25T09:00:00Z",
    media_urls=["https://cdn.example.com/holiday.jpg"]
)

print(f"Scheduled for: {result['scheduled_for']}")

Get Analytics

# Check post performance
analytics = await get_post_analytics(
    post_id="abc123"
)

print(f"Analytics: {analytics['analytics']}")

View Post History

# Access as resource
history = await mcp.get_resource("ayrshare://history")
print(history)

Error Handling

The server provides detailed error messages for common issues:

• Authentication Errors: Invalid API key or missing credentials
• Validation Errors: Invalid platforms, malformed dates, missing required fields
• API Errors: Rate limits, platform-specific errors, network issues

All tools return a status field ("success" or "error") and a message field for errors.

Development

Project Structure

ayrshare-mcp/
├── src/
│   ├── server.py           # FastMCP server with tools and resources
│   └── ayrshare_client.py  # Async Ayrshare API client wrapper
├── pyproject.toml          # Project dependencies and metadata
├── .env.example            # Environment variable template
├── .gitignore              # Git ignore patterns
└── README.md               # This file

Running Tests

# Install dev dependencies
pip install -e ".[dev]"

# Run tests
pytest

# Run with coverage
pytest --cov=src --cov-report=html

Code Quality

# Format code
black src/

# Lint code
ruff check src/

Security Best Practices

• Never commit .env files: API keys should only be in .env (gitignored)
• Use environment variables: Always load credentials from environment
• Rotate API keys regularly: Generate new keys periodically
• Monitor usage: Check Ayrshare dashboard for unusual activity
• Use profile keys: For multi-tenant scenarios, use separate profile keys

Troubleshooting

"Invalid API key" Error

• Verify API key in Ayrshare dashboard
• Check that key is correctly set in .env file
• Ensure .env file is in the project root directory

"Platform not connected" Error

• Go to Ayrshare dashboard
• Connect the social media account
• Verify connection status shows "Active"

Scheduled Posts Not Publishing

• Check scheduled date is in the future
• Verify timezone (use UTC or include timezone offset)
• Confirm platform supports scheduling

Media Upload Failures

• Ensure URLs are publicly accessible
• Check file size limits (varies by platform)
• Verify media format is supported by target platform

API Rate Limits

Ayrshare enforces rate limits based on your plan:

• Free Tier: 5 posts per month
• Starter Plan: 50 posts per month
• Professional Plan: 500 posts per month
• Business Plan: Custom limits

Monitor your usage in the Ayrshare dashboard.

Resources

• Ayrshare Website
• Ayrshare API Documentation
• FastMCP Documentation
• Get API Key
• Connect Social Accounts

License

MIT License - see LICENSE file for details

Contributing

Contributions are welcome! Please:

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Add tests for new functionality
5. Submit a pull request

Support

For issues and questions:

• MCP Server Issues: Open an issue in this repository
• Ayrshare API Issues: Contact Ayrshare support
• General Questions: Check the Ayrshare documentation

Roadmap

Recently implemented:

• [x] Bulk post operations
• [x] Advanced scheduling (recurring posts, evergreen content)
• [x] Webhook support for post status updates
• [x] Media library management
• [x] Comments API (read, add, reply, delete)
• [x] Direct Messages API (send, read, manage conversations)
• [x] Google Business Reviews API (read, respond, manage)
• [x] Links API (URL shortening and analytics)
• [x] Ads API (create, manage, analyze campaigns)
• [x] Auto-hashtag generation
• [x] First comment automation
• [x] Approval workflows

Future enhancements planned:

• [ ] Post templates and content library
• [ ] A/B testing support
• [ ] Enhanced analytics with charts
• [ ] RSS feed integration
• [ ] Content calendar view
• [ ] Social listening and monitoring
• [ ] Competitor analysis tools

---

Built with FastMCP - A modern framework for building Model Context Protocol servers.