Citadelle MCP Server

An official Model Context Protocol (MCP) server for Citadelle Options - allowing AI agents (like Claude, Cursor, and Windsurf) to securely interact with decentralized US Stock options markets on the EVM / Robinhood Chain.

🌟 Features

This MCP server equips AI Assistants with three powerful, context-aware tools:

• get_markets_liquidity: Fetches all available US Stock options markets (e.g., AAPL, TSLA, NVDA) from the Citadelle Indexer and filters them by available liquidity. The AI instantly knows which markets are active, what the current strike prices are, and whether there is enough liquidity to execute a trade.

• get_wallet_portfolio: Fetches the open Long and Short (Written) US Stock options positions for any provided EVM wallet address.

• generate_trade_link: Safely prepares a transaction URL. Instead of having the AI sign a transaction directly with private keys (which is a massive security risk), the AI returns a secure deep-link to the Citadelle Web UI. The user can then review and sign the transaction safely using their browser wallet (MetaMask, Rabby, etc.).

Related MCP server: E*TRADE MCP Server

🚀 Usage Examples (Prompts)

Once the MCP Server is connected to your AI Assistant, you can use natural language to interact with Citadelle. Try these prompts:

Exploring Markets:

"I want to trade US Stocks on Citadelle. What AAPL options are currently available and have liquidity?" "Show me all available Call options for TSLA."

Checking Portfolio:

"Show me my open options portfolio for wallet 0xYourWalletAddress..." "Do I have any active put options for NVDA in my wallet?"

Executing Trades:

"Buy 100 AAPL Call Options for me." (The AI will find the best market, generate a secure trade link, and provide it to you to click and sign). "I want to write a Put option for TSLA to earn some premium. Generate a transaction link for me."

📦 Installation & Configuration

You can run this server directly via npx in any compatible MCP client without needing to install or clone the repository locally!

Configuring in Cursor / Windsurf

1. Open Settings -> MCP.

2. Add a new MCP Server.

3. Name: Citadelle

4. Type: command

5. Command: npx

6. Args: -y citadelle-mcp@latest (This ensures the AI always fetches the newest protocol updates).

7. Set the Environment Variables within the Cursor UI (see the Environment Variables section below).

Configuring in Claude Desktop

Add the following configuration to your claude_desktop_config.json:

{
  "mcpServers": {
    "citadelle": {
      "command": "npx",
      "args": ["-y", "citadelle-mcp@latest"],
      "env": {
        "RPC_URL": "https://api.citadelleoption.tech/api/rpc",
        "WEB_UI_BASE_URL": "https://citadelleoption.tech",
        "API_BASE_URL": "https://api.citadelleoption.tech/api",
        "CONTRACT_ADDRESS": "0xe268a55dD2672Ddb6d7727283B27d9BE601c421a"
      }
    }
  }
}

⚙️ Environment Variables

To ensure the AI routes your requests to the correct network and API, you must configure the following environment variables:

🛠️ Local Development

If you wish to contribute or run the MCP server locally from source:

1. Clone the repository and install dependencies:

   npm install

2. Create a .env file from the example:

   cp .env.example .env

3. Build the TypeScript code:

   npm run build

4. To link it locally to an MCP client like Cursor, point the MCP settings to your local dist/index.js file:

   • Command: node

   • Args: /absolute/path/to/citadelle-mcp/dist/index.js

🔄 Troubleshooting

If your AI assistant is returning outdated market data or generating incorrect links, it may be using a cached version of the MCP Server. To force an update:

• Claude Desktop: Quit the application completely (Cmd+Q / Ctrl+Q) and reopen it. This forces npx to fetch the @latest version.

• Cursor/Windsurf: Restart the MCP Server from the settings panel, or manually run npx clear-npx-cache in your terminal before restarting.

License

MIT