Warpcast MCP Server

A Model Context Protocol (MCP) server for Warpcast integration that allows you to use Claude to interact with your Warpcast account.
The implementation now follows the FastMCP style server from the MCP Python SDK.

Features

Post casts to your Warpcast account
Read casts from Warpcast
Search casts by keyword or hashtag
Browse and interact with channels
Follow/unfollow channels
Get trending casts

Warpcast API https://docs.farcaster.xyz/reference/warpcast/api

Usage

mcp-warpcast-server is usually launched automatically by Claude Desktop's MCP client when the Warpcast tools are configured. After the server starts you can ask Claude to:

"Post a cast about [topic]"
"Read the latest casts from [username]"
"Search for casts about [topic]"
"Show me trending casts on Warpcast"
"Show me popular channels on Warpcast"
"Get casts from the [channel] channel"
"Follow the [channel] channel for me"

Available Tools

This MCP server provides several tools that Claude can use:

post-cast: Create a new post on Warpcast (max 320 characters)
get-user-casts: Retrieve recent casts from a specific user
search-casts: Search for casts by keyword or phrase
get-trending-casts: Get the currently trending casts on Warpcast
get-all-channels: List available channels on Warpcast
get-channel: Get information about a specific channel
get-channel-casts: Get casts from a specific channel
follow-channel: Follow a channel
unfollow-channel: Unfollow a channel

Setup

Claude Desktop normally launches this server for you when the Warpcast tools are configured. The steps below are only needed if you want to run the server manually for development.

Create a Python virtual environment (Python 3.11 or newer is recommended):
```
python3 -m venv venv
source venv/bin/activate
```
Install dependencies (the requirements include the MCP Python SDK):
```
pip install -r requirements.txt
```
Provide a Warpcast API token:
- Log in to Warpcast and open Settings > Developer.
- Click Create API Token and copy the value.
- Add WARPCAST_API_TOKEN under the env section of your Claude desktop configuration.
- If starting the server manually, you can instead export the token in your shell:
```
export WARPCAST_API_TOKEN=YOUR_TOKEN
```
The server validates this variable on startup. If it is missing, a warning is logged and authorized requests will respond with HTTP 500 errors.
(Optional) Start the server manually: The app variable exported from main.py is created using mcp.streamable_http_app() so it can be served by any ASGI server.
```
uvicorn main:app --reload
```

The server exposes HTTP endpoints matching the tools listed above and a standard /mcp endpoint provided by FastMCP.

Using with Claude Desktop

Follow these steps to access the Warpcast tools from Claude's desktop application:

Start the server (or let Claude launch it) using the setup instructions above.
Open your Claude configuration file:
- macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
- Windows: %APPDATA%\Claude\claude_desktop_config.json
Add the Warpcast server under the mcpServers key. Replace the path with the location of this repository:

{
  "mcpServers": {
    "warpcast": {
      "command": "uvicorn",
      "args": [
        "--app-dir",
        "/ABSOLUTE/PATH/TO/mcp-warpcast-server",
        "main:app",
        "--port",
        "8000"
      ],
      "url": "http://localhost:8000/mcp",
      "env": {
        "WARPCAST_API_TOKEN": "YOUR_API_TOKEN"
      }
    }
  }
}

Specifying a url tells Claude Desktop to communicate with the server over HTTP using Server-Sent Events instead of standard input and output. If you omit url, Claude Desktop defaults to communicating via standard input and output (stdio), which will not work with this server.

Save the file and restart Claude Desktop. You should now see a hammer icon in the chat input that lets you use the Warpcast tools.

Running Tests

Unit tests are written with pytest and use FastAPI's TestClient (installed via fastapi[testclient]). Create a virtual environment, install dependencies and run the suite:

python3 -m venv venv
source venv/bin/activate
pip install -r requirements.txt
make test        # or simply `pytest`

The tests mock the Warpcast API layer so no network connection is required.

MCP Compatibility

This server uses the official MCP Python SDK and is fully compatible with the Model Context Protocol. Clients can connect to the /mcp endpoint provided by FastMCP and interact with the tools defined here.

License

This project is licensed under the MIT License.