Typefully-MCP-Server

Typefully MCP Server

A Model Context Protocol (MCP) server that provides tools for interacting with the Typefully API. This server allows you to create drafts, schedule tweets, manage drafts, and handle notifications programmatically.

Features

• Create Drafts: Create tweet drafts and threads
• Schedule Content: Schedule drafts for specific times or next available slot
• Manage Drafts: Get recently scheduled and published drafts
• Notifications: Retrieve and manage notifications
• Thread Creation: Convenient thread creation with multiple tweets
• Auto Features: Support for AutoRT and AutoPlug

Installation

Option 1: Automated Setup (Recommended)

Run the setup script which will create a virtual environment and install dependencies:

chmod +x setup.sh
./setup.sh

Then activate the virtual environment:

source venv/bin/activate

Option 2: Manual Setup

1. Clone or download this repository
2. Create a virtual environment:

python3 -m venv venv
source venv/bin/activate

3. Install the required dependencies:

pip install -r requirements.txt

4. Set up your Typefully API key as an environment variable:

export TYPEFULLY_API_KEY="your_api_key_here"

You can get an API key from Typefully Settings > Integrations.

MCP Client Configuration

To use this server with an MCP client (like Claude Desktop, Continue, or other MCP-compatible tools), add the following configuration:

For MCP Clients

Add this to your MCP client configuration file (usually config.json or similar):

{
    "mcpServers": {
        "typefully": {
            "type": "stdio",
            "command": "/path/to/your/typefully/venv/bin/python",
            "args": ["/path/to/your/typefully/server.py"],
            "env": {
                "TYPEFULLY_API_KEY": "your_actual_api_key_here"
            }
        }
    }
}

Configuration Options

Replace the paths and API key with your actual values:

• /path/to/your/typefully/ - Replace with the full path to where you installed this server
• your_actual_api_key_here - Replace with your Typefully API key from Settings > Integrations

Example Configurations

Option 1: Using Virtual Environment Python (Recommended)

{
    "mcpServers": {
        "typefully": {
            "type": "stdio",
            "command": "/Users/yourname/path/to/typefully/venv/bin/python",
            "args": ["/Users/yourname/path/to/typefully/server.py"],
            "env": {
                "TYPEFULLY_API_KEY": "your_actual_api_key_here"
            }
        }
    }
}

Option 2: Using System Python

{
    "mcpServers": {
        "typefully": {
            "type": "stdio",
            "command": "python3",
            "args": ["/Users/yourname/path/to/typefully/server.py"],
            "env": {
                "TYPEFULLY_API_KEY": "your_actual_api_key_here"
            }
        }
    }
}

Option 3: Using a Wrapper Script

Create a run script:

#!/bin/bash
cd /path/to/your/typefully
source venv/bin/activate
python3 server.py

Then configure:

{
    "mcpServers": {
        "typefully": {
            "type": "stdio",
            "command": "/path/to/your/typefully/run.sh",
            "args": [],
            "env": {
                "TYPEFULLY_API_KEY": "your_actual_api_key_here"
            }
        }
    }
}

Finding Your Installation Path

To find the correct path for your installation:

# Navigate to your typefully directory
cd /path/to/your/typefully

# Get the full path
pwd

# This will show something like:
# /Users/yourname/Agents/MCP/typefully

Use this full path in your MCP client configuration.

Usage

Running the Server Standalone

Make sure your virtual environment is activated first:

source venv/bin/activate
python server.py

When you're done, you can deactivate the virtual environment:

deactivate

Available Tools

create_draft

Create a draft tweet or thread in Typefully.

Parameters:

• content (required): The content of the tweet/thread
• threadify (optional): Auto-split content into multiple tweets
• share (optional): Include a share_url in the response
• schedule_date (optional): ISO date or "next-free-slot"
• auto_retweet_enabled (optional): Enable AutoRT
• auto_plug_enabled (optional): Enable AutoPlug

Example:

# Create a simple draft
create_draft("Hello, world! This is my first tweet via MCP.")

# Create a scheduled thread
create_draft(
    content="First tweet\n\n\n\nSecond tweet\n\n\n\nThird tweet",
    schedule_date="next-free-slot",
    auto_retweet_enabled=True
)

get_recently_scheduled_drafts

Get a list of recently scheduled drafts.

Parameters:

• content_filter (optional): Filter by "threads" or "tweets"

get_recently_published_drafts

Get a list of recently published drafts.

get_notifications

Get latest notifications.

Parameters:

• kind (optional): Filter by "inbox" or "activity"

mark_notifications_read

Mark notifications as read.

Parameters:

• kind (optional): Type of notifications ("inbox" or "activity")
• username (optional): Specific account username

schedule_draft_for_next_slot

Convenience function to schedule a draft for the next available time slot.

create_thread

Create a thread by providing an array of tweet contents.

Parameters:

• tweets (required): List of tweet contents
• Additional options like schedule_date, auto_retweet_enabled, etc.

Example:

create_thread([
    "This is the first tweet in my thread",
    "This is the second tweet with more details",
    "And this concludes my thread!"
], schedule_date="next-free-slot")

Content Formatting

Threading

To create a thread manually in the content parameter, separate tweets with 4 consecutive newlines:

First tweet


Second tweet


Third tweet

Automatic Threading

Set threadify=True to automatically split long content into multiple tweets.

API Key Management

The server looks for the API key in the TYPEFULLY_API_KEY environment variable. Make sure to:

1. Get your API key from Typefully Settings > Integrations
2. Set it in your MCP client configuration or as an environment variable
3. Keep your API key secure and never commit it to version control

Testing Your Setup

To verify your server is working correctly:

1. Test the server standalone:

   source venv/bin/activate
   python test.py
   

2. Test with your MCP client: Once configured, try using one of the available tools like get_recently_published_drafts to verify the connection.

Error Handling

The server includes comprehensive error handling for:

• Missing API keys
• Network errors
• Invalid API responses
• Malformed requests

All errors are returned as descriptive exception messages.

Compliance Notes

When using this server to schedule content, make sure to:

• Adhere to X (Twitter) automation rules
• Follow general social media posting guidelines
• Avoid spammy or automated behavior that could result in account restrictions

Development

Project Structure

typefully/
├── server.py          # Main MCP server implementation
├── config.json        # MCP server configuration
├── requirements.txt   # Python dependencies
├── setup.sh          # Automated setup script
├── test.py           # Test suite
├── .env.example      # Environment variable template
├── .gitignore        # Git ignore rules
└── README.md         # This file

Contributing

Feel free to submit issues and enhancement requests!

Support

If you find this project helpful, consider:

• ⭐ Starring this repository
• Supporting my work on GitHub Sponsors
• 🌐 Visiting my website at SethRose.dev

License

This project is open source and available under the MIT License.

Created by Seth Rose | GitHub