typefully-mcp-server

Typefully MCP Server

A Model Context Protocol (MCP) server for Typefully API integration, built with TypeScript and Node.js. This server allows AI assistants (like Claude) to create and manage Twitter drafts through Typefully.

Features

• Create Drafts: Create single tweets or multi-tweet threads
• Schedule Posts: Schedule tweets for specific times
• Auto Features: Enable auto-retweet and auto-plug
• Retrieve Drafts: Get scheduled and published drafts
• Thread Support: Automatic thread creation using newline separators

Prerequisites

• Node.js 18.x or higher
• A Typefully account with API access
• Typefully API key (get it from Settings > Integrations in Typefully)

Installation

Option 1: NPX (Recommended)

Run directly without installation:

npx typefully-mcp-server

Option 2: Global Installation

npm install -g typefully-mcp-server
typefully-mcp-server

Option 3: From Source

• Clone the repository:

git clone https://github.com/yourusername/typefully-mcp-server.git
cd typefully-mcp-server

• Install dependencies:

npm install

• Build the project:

npm run build

Configuration

Set your Typefully API key as an environment variable:

export TYPEFULLY_API_KEY="your_api_key_here"

Or create a .env file:

TYPEFULLY_API_KEY=your_api_key_here

Usage

Running the Server

npm start

Or for development:

npm run dev

Claude Desktop Integration

Add this server to your Claude Desktop configuration file:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json Windows: %APPDATA%/Claude/claude_desktop_config.json

Option 1: Using Absolute Node Path (Recommended for Local Development):

Important: If you get a "spawn node ENOENT" error, Claude Desktop can't find the node command. Use the absolute path to node instead:

First, find your node path: which node

{
  "mcpServers": {
    "typefully": {
      "command": "/opt/homebrew/opt/nvm/versions/node/v22.16.0/bin/node",
      "args": ["/path/to/your/project/dist/index.js"],
      "env": {
        "TYPEFULLY_API_KEY": "your_api_key_here"
      }
    }
  }
}

Option 2: Using NPX (After Publishing to NPM):

{
  "mcpServers": {
    "typefully": {
      "command": "npx",
      "args": ["typefully-mcp-server"],
      "env": {
        "TYPEFULLY_API_KEY": "your_api_key_here"
      }
    }
  }
}

Available Tools

create_draft

Create a new draft on Typefully.

Parameters:

• content (required): The tweet content or thread
• threadify (optional): Auto-split content into tweets
• schedule_date (optional): ISO date string for scheduling
• auto_retweet_enabled (optional): Enable auto-retweet
• auto_plug_enabled (optional): Enable auto-plug

Example:

Create a tweet: "Hello world! This is my first tweet via MCP."

Thread Example:

Create a thread about AI:

"AI is transforming how we work and live.

\n\n\n\n

From automating routine tasks to enabling creative breakthroughs, AI tools are becoming essential.

\n\n\n\n

The key is learning to collaborate with AI rather than compete against it."

get_scheduled_drafts

Retrieve your recently scheduled drafts.

Example:

Show me my scheduled tweets.

get_published_drafts

Retrieve your recently published drafts.

Example:

Show me my recent published tweets.

Thread Creation

To create multi-tweet threads, separate individual tweets with four consecutive newlines (\n\n\n\n) in your content.

Development

Scripts

• npm run build - Build the TypeScript project
• npm run dev - Run in development mode with auto-reload
• npm run lint - Run ESLint
• npm run typecheck - Run TypeScript type checking

Project Structure

src/
├── index.ts        # Entry point
├── server.ts       # MCP server implementation
├── client.ts       # Typefully API client
└── types.ts        # Type definitions

API Reference

This server integrates with the Typefully API v1. For more information about the API, visit the official documentation.

Error Handling

The server includes comprehensive error handling for:

• Invalid API keys
• Network failures
• Malformed requests
• API rate limiting

Common Issues

"spawn node ENOENT" Error in Claude Desktop

This error occurs when Claude Desktop can't find the node command because GUI applications don't inherit the same PATH as your terminal.

Solution: Use the absolute path to node in your Claude Desktop configuration:

• Find your node path: which node
• Use the full path in your config instead of just "node"

Example:

{
  "mcpServers": {
    "typefully": {
      "command": "/opt/homebrew/opt/nvm/versions/node/v22.16.0/bin/node",
      "args": ["/path/to/dist/index.js"],
      "env": {
        "TYPEFULLY_API_KEY": "your_api_key_here"
      }
    }
  }
}

Publishing to NPM

To publish this package so users can run npx typefully-mcp-server:

• Update package.json with your details (author, repository URLs)
• Check name availability: npm view typefully-mcp-server
• Login to NPM: npm login
• Build and publish: npm run build && npm publish

See PUBLISHING.md for detailed instructions.

Contributing

• Fork the repository
• Create a feature branch
• Make your changes
• Run tests and linting
• Submit a pull request

License

MIT License - see LICENSE file for details.

Acknowledgments

• Inspired by the Python Typefully MCP Server
• Built with the Model Context Protocol SDK