Coin Flip MCP Server

An MCP server that provides true random coin flips using random.org's randomness API. This server demonstrates the Model Context Protocol by providing a tool for generating random outcomes with configurable sides.

Features

Tools

• flip_coin - Flip a coin with configurable number of sides
  • Optional sides parameter (default: 2)
  • Uses true randomness from random.org
  • Special handling for edge cases (0, 1, or negative sides)
  • For 2 sides: Returns "Heads" or "Tails"
  • For 3 sides: Returns "Heads", "Tails", or "_"
  • For n>3 sides: Returns "It landed on side X"

Development

Install dependencies:

npm install

Build the server:

npm run build

For development with auto-rebuild:

npm run watch

Debugging

Since MCP servers communicate over stdio, debugging can be challenging. We recommend using the MCP Inspector:

npx @modelcontextprotocol/inspector node build/index.js

Installation

To use with Claude Desktop, add the server config:

On MacOS: ~/Library/Application Support/Claude/claude_desktop_config.json
On Windows: %APPDATA%/Claude/claude_desktop_config.json

{
  "mcpServers": {
    "coin-flip": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-coin-flip"]
    }
  }
}

Example Usage

Once connected to an MCP client like Claude Desktop, you can use natural language to interact with the coin flip tool. For example:

• "Flip a coin"
• "Roll a 6-sided die"
• "Give me a random number between 1 and 20"

The server will use true randomness from random.org to generate the result.

License

MIT