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

1. post-cast: Create a new post on Warpcast (max 320 characters)
2. get-user-casts: Retrieve recent casts from a specific user
3. search-casts: Search for casts by keyword or phrase
4. get-trending-casts: Get the currently trending casts on Warpcast
5. get-all-channels: List available channels on Warpcast
6. get-channel: Get information about a specific channel
7. get-channel-casts: Get casts from a specific channel
8. follow-channel: Follow a channel
9. 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.

1. Create a Python virtual environment (Python 3.11 or newer is recommended):

   python3 -m venv venv
   source venv/bin/activate
   

2. Install dependencies (the requirements include the MCP Python SDK):

   pip install -r requirements.txt
   

3. 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.

4. (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:

1. Start the server (or let Claude launch it) using the setup instructions above.
2. Open your Claude configuration file:
   • macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
   • Windows: %APPDATA%\Claude\claude_desktop_config.json
3. 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.

4. 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.