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

```bash
npx typefully-mcp-server
```

### Option 2: Global Installation

```bash
npm install -g typefully-mcp-server
typefully-mcp-server
```

### Option 3: From Source

1. Clone the repository:

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

2. Install dependencies:

```bash
npm install
```

3. Build the project:

```bash
npm run build
```

## Configuration

Set your Typefully API key as an environment variable:

```bash
export TYPEFULLY_API_KEY="your_api_key_here"
```

Or create a `.env` file:

```
TYPEFULLY_API_KEY=your_api_key_here
```

## Usage

### Running the Server

```bash
npm start
```

Or for development:

```bash
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 NPX (Recommended):

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

#### Option 2: Using Absolute Node Path (For Local Development):

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

```json
{
  "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"
      }
    }
  }
}
```

## 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."
```

**Note**: After installation via NPX, you can simply tell Claude: "Create a tweet saying 'Hello from Typefully MCP!'" and it will work automatically.

### 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](https://support.typefully.com/en/articles/8718287-typefully-api).

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

1. Find your node path: `which node`
2. Use the full path in your config instead of just "node"

Example:

```json
{
  "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"
      }
    }
  }
}
```

## Contributing

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Run tests and linting
5. Submit a pull request

## License

MIT License - see LICENSE file for details.

## Acknowledgments

- Inspired by the [Python Typefully MCP Server](https://github.com/pepuscz/typefully-mcp-server)
- Built with the [Model Context Protocol SDK](https://github.com/modelcontextprotocol/typescript-sdk)