A demo MCP server that implements a classic Magic 8-Ball oracle.
Magic 8-Ball MCP Server
A demo Model Context Protocol server that implements a classic Magic 8-Ball oracle. Built with TypeScript and Bun.
What's Inside
| MCP Primitive | Name | Description |
|---|---|---|
| Tool | shake |
Ask a yes/no question, get a random 8-Ball answer |
| Prompt | ask-the-8-ball |
Reusable prompt template for consulting the oracle |
| Resource | magic-8-ball://responses |
The complete list of 20 classic responses |
Prerequisites
- Bun v1.0+
- Claude Desktop (for installing the
.mcpbbundle)
Getting Started
# Install dependencies
bun install
# Run the server directly (stdio transport)
bun run start
Testing with MCP Inspector
The MCP Inspector provides a browser UI for interacting with your server.
bun run inspect
This opens http://localhost:6274 where you can:
- Tools — Call
shakewith a question and see random 8-Ball responses - Prompts — Get the
ask-the-8-ballprompt template with a question filled in - Resources — Read
magic-8-ball://responsesto see all 20 classic answers
Building & Packaging for Claude Desktop
1. Build
Compile TypeScript to JavaScript so the bundle can run with Node.js (which ships with Claude Desktop):
bun run build
This creates dist/index.js — a single-file bundle with all dependencies included.
2. Create the manifest
If you haven't already, initialize the MCPB manifest:
bunx @anthropic-ai/mcpb init
A manifest.json is already included in this repo. You can validate it:
bunx @anthropic-ai/mcpb validate manifest.json
3. Pack
bunx @anthropic-ai/mcpb pack .
This creates a .mcpb file (e.g., magic-8-ball-mcp-1.0.0.mcpb).
4. Install in Claude Desktop
Double-click the .mcpb file (or open it with Claude Desktop). Claude will show an installation dialog — click Install and the Magic 8-Ball tools will be available in your conversations.
Project Structure
bun-demo-mcp/
├── .claude/
│ └── CLAUDE.md # Claude Code project instructions
├── dist/
│ └── index.js # Compiled bundle (generated)
├── src/
│ ├── index.ts # MCP server (tool + prompt + resource)
│ └── responses.ts
├── bun.lock
├── manifest.json # MCPB bundle manifest
├── package.json
├── README.md
└── tsconfig.json
License
MIT
Tools (1)
shakeAsk a yes/no question and receive a random 8-Ball answer.Configuration
{"mcpServers": {"magic-8-ball": {"command": "bun", "args": ["run", "start"]}}}