Warpcast Model Context Protocol Endpoint

This implementation serves as a Model Context Protocol (MCP) node for seamless integration with the Warpcast platform, enabling Claude to interact with your personal Warpcast account. The architecture adheres to the specification established by the FastMCP framework, as seen in the MCP Python SDK implementation style.

Core Capabilities

• Draft and dispatch new posts (casts) to your Warpcast feed.
• Fetch and display recent casts from Warpcast.
• Execute keyword or hashtag-based searches across cast content.
• Examine and interact with various content channels.
• Toggle subscription status for specified channels.
• Access currently popular or trending casts.

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

Operational Guidance

Typically, the mcp-warpcast-integration-node is automatically initiated by the Claude Desktop MCP client upon correct configuration of the Warpcast tools. Once the service is active, you can instruct Claude to perform actions such as:

• "Publish a message regarding [subject]"
• "Retrieve the most recent posts by [user identifier]"
• "Locate casts associated with [search term]"
• "Display the current trending material on Warpcast"
• "List the most active channels on Warpcast"
• "Fetch discourse from the [channel name] channel"
• "Subscribe me to the [channel name] channel"

Exposed Tools/Functions

This server exposes the following utilities for Claude's utilization:

1. post-cast: Functionality to generate and submit a new publication on Warpcast (character limit of 320).
2. get-user-casts: Utility to pull historical recent casts associated with a designated account.
3. search-casts: Tool designed for querying casts based on specific text strings or tags.
4. get-trending-casts: Method to fetch the currently most popular casts being shared.
5. get-all-channels: Retrieves a comprehensive listing of all publicly available channels.
6. get-channel: Retrieves metadata and details pertaining to a specific channel entity.
7. get-channel-casts: Fetches the stream of casts posted within a designated channel.
8. follow-channel: Subscribes the user to updates from a specified channel.
9. unfollow-channel: Revokes the user's subscription from a specified channel.

Deployment Procedure

Claude Desktop generally manages the activation of this node automatically when Warpcast tooling is set up. The subsequent instructions are for manual initiation, typically for development or diagnostics.

1. Establish an isolated Python environment (Python 3.11+ suggested): bash python3 -m venv venv source venv/bin/activate

2. Install necessary project dependencies (includes the core MCP Python SDK): bash pip install -r requirements.txt

3. Supply the requisite Warpcast authentication credential:

4. Navigate to Warpcast and access Settings > Developer.
5. Select Create API Token and securely copy the resulting secret value.
6. Integrate WARPCAST_API_TOKEN within the env section of your Claude desktop configuration file.
7. Alternatively, for manual server invocation, set the token as an environment variable in your shell: bash export WARPCAST_API_TOKEN=YOUR_SECRET_KEY

The server rigorously validates this environment variable during startup. Omission results in a logged warning, and subsequent authenticated operations will yield HTTP 500 responses.

1. (Optional) Initiate the server process manually: The primary application variable, designated as app, is instantiated via mcp.streamable_http_app(), rendering it compatible with any standard ASGI server. bash uvicorn main:app --reload

The service exposes dedicated HTTP entry points corresponding to the tools detailed above, alongside the standard /mcp interface mandated by FastMCP conventions.

Integration with Claude Desktop

Follow these procedural steps to grant Claude Desktop access to the Warpcast toolset:

1. Ensure the server is operational (either autonomously launched or manually started) following the setup instructions.
2. Access your Claude configuration file via the location specific to your operating system:
3. macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
4. Windows: %APPDATA%\Claude\claude_desktop_config.json
5. Introduce the Warpcast server definition under the mcpServers mapping. Substitute the placeholder path with the absolute directory path to this repository's root:

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

The inclusion of a url parameter directs Claude Desktop to communicate via HTTP utilizing Server-Sent Events (SSE). If url is omitted, the default behavior reverts to standard input/output (stdio) communication, which this specific server implementation does not support.

1. Save the configuration file and restart the Claude Desktop application. A tool icon (resembling a hammer) should then appear in the chat interface, signifying the Warpcast capabilities are ready for use.

Testing Protocol

Unit validation is performed using pytest, leveraging FastAPI's TestClient (included via fastapi[testclient]). After environment setup and dependency installation:

bash python3 -m venv venv source venv/bin/activate pip install -r requirements.txt pytest

Tests are engineered to mock all external Warpcast API interactions, thus negating the necessity for a live network connection during execution.

MCP Compliance

This service is built upon the official MCP Python SDK, ensuring comprehensive adherence to the Model Context Protocol specifications. Connectivity is established through the FastMCP-provided /mcp endpoint, enabling interaction with the defined functional units.

Licensing Information

This software is distributed under the terms of the MIT License.