{"slug": "building-a-custom-mcp-server-for-claude-code-a-fortune-telling-tool-with-fastmcp", "title": "Building a Custom MCP Server for Claude Code — A Fortune-Telling Tool with FastMCP", "summary": "A developer demonstrates how to build a custom MCP (Model Context Protocol) server for Claude Code using the FastMCP library, creating a fortune-telling tool in just a few dozen lines of Python. The tool, named 'uranai', uses a seeded random number generator to provide daily fortunes based on a user's name and optional birthday. FastMCP handles the protocol plumbing, allowing developers to focus on writing simple Python functions with a decorator.", "body_md": "\"MCP servers sound complicated\" — if that's your reaction, FastMCP might change your mind. It handles almost all the plumbing for you. Add one decorator to a plain Python function, and you've got a custom tool Claude Code can call.\n\nIn this post, we'll build a small fortune-telling tool as a learning exercise, and walk through what FastMCP is actually doing for you along the way.\n\nMCP (Model Context Protocol) is a common standard for giving AI models like Claude \"external tools\" to work with.\n\nAn AI model itself is great at generating text, but on its own it can't do concrete things like \"tell today's fortune based on the date\" or \"query an internal database.\"\n\nThat's where an MCP server comes in: you register callable tools on it, and Claude Code invokes them whenever it needs to.\n\nHand-writing an MCP server from scratch is a fair amount of work, but with FastMCP you can build a working fortune-telling tool that Claude Code can call in just a few dozen lines of code.\n\nNormally, an MCP server has to implement a lot of low-level protocol details — what message format to use, how to advertise the list of available tools, and so on. FastMCP takes care of all that \"plumbing\" for you.\n\nAll you do as a developer is write a normal Python function and mark it with `@mcp.tool`\n\n. FastMCP inspects the function's argument types and return type to auto-generate the schema (the \"instruction manual\") that gets handed to the AI. Since none of the transport or protocol details are something you need to think about, anyone who's written a basic web app can have their first tool running in a few minutes.\n\nNote on decorator syntax: the standalone`fastmcp`\n\npackage (what we're using here) accepts a bare`@mcp.tool`\n\n, no parentheses needed. If you're instead using the`MCPServer`\n\nbundled with the official`mcp`\n\nPython SDK, the decorator requires parentheses:`@mcp.tool()`\n\n. Mixing the two up is a common source of confusing errors, so if you copy code from a different MCP tutorial, double-check which package it's using.\n\nYou'll need Python 3.10 or later.\n\n```\npython --version\n```\n\nIf it's not installed, grab it from [python.org](https://www.python.org/).\n\nThen create and activate a virtual environment:\n\n```\n# macOS / Linux\npython -m venv venv\nsource venv/bin/activate\n\n# Windows\npython -m venv venv\nvenv\\Scripts\\activate.bat\n```\n\nOnce activated, you should see `(venv)`\n\nat the start of your prompt.\n\nInstall FastMCP:\n\n```\npip install fastmcp\n```\n\nThat's it — no database, no config files.\n\nCreate a project folder and, inside it, a `server.py`\n\nfile with the following:\n\n``` python\nimport random\nfrom datetime import date\nfrom fastmcp import FastMCP\n\n# Create the server (\"uranai\" is Japanese for \"fortune-telling\" — the name of this tool group)\nmcp = FastMCP(\"uranai\")\n\n@mcp.tool\ndef fortune(name: str, birthday: str = \"\") -> str:\n    \"\"\"Tells today's fortune based on a name (and optionally a birthday).\"\"\"\n    # Seed the RNG with name + birthday + today's date, so the result\n    # stays the same for a given person on a given day, but changes daily.\n    seed = f\"{name}|{birthday}|{date.today().isoformat()}\"\n    rng = random.Random(seed)\n\n    levels = [\"Great luck\", \"Good luck\", \"Modest luck\", \"Luck\", \"Fading luck\", \"Bad luck\"]\n    items = [\"reading a book\", \"taking a walk\", \"coffee\", \"sleeping early\", \"a new app\", \"cleaning\"]\n    colors = [\"red\", \"blue\", \"green\", \"yellow\", \"white\", \"purple\"]\n\n    return (\n        f\"Today's fortune for {name}\\n\"\n        f\"Fortune: {rng.choice(levels)}\\n\"\n        f\"Lucky activity: {rng.choice(items)}\\n\"\n        f\"Lucky color: {rng.choice(colors)}\\n\"\n        f\"Lucky number: {rng.randint(1, 49)}\"\n    )\n\nif __name__ == \"__main__\":\n    mcp.run()\n```\n\nThree things matter here:\n\n`FastMCP(\"uranai\")`\n\ncreates the server instance.`@mcp.tool`\n\nto the function is all it takes to turn it into something Claude can call.`\"\"\"...\"\"\"`\n\npart) is what the AI reads to decide The trick worth noting is seeding the random number generator with today's date. That gives you fortune-telling-app behavior for free: the same person gets the same result if asked again on the same day, and a different result the next day.\n\nFrom the project directory, run:\n\n```\npython server.py\n```\n\nIf it starts without errors, you're ready to connect it to Claude Code.\n\nIf you don't have the Claude Code CLI installed yet, install it first — see the [official installation docs](https://code.claude.com/docs/en/installation) for your platform (macOS, Linux, or Windows).\n\nThen register the server:\n\n```\nclaude mcp add uranai -- python /path/to/server.py\n```\n\nReplace `/path/to/server.py`\n\nwith the actual path (if you're using a virtual environment, point to that environment's Python executable to be safe).\n\nRestart or reload Claude Code, and the `uranai`\n\nserver should be recognized. You can check connection status with the `/mcp`\n\ncommand.\n\nIf you're using the Claude desktop app instead, add this to your config file:\n\n`~/Library/Application Support/Claude/claude_desktop_config.json`\n\n`%APPDATA%\\Claude\\claude_desktop_config.json`\n\n```\n{\n  \"mcpServers\": {\n    \"uranai\": {\n      \"command\": \"/path/to/venv/bin/python\",\n      \"args\": [\"/path/to/uranai/server.py\"]\n    }\n  }\n}\n```\n\n(On Windows, `command`\n\nwould instead point to something like `C:\\\\Users\\\\yourname\\\\uranai\\\\venv\\\\Scripts\\\\python.exe`\n\n.)\n\nOpen Claude Code, ask it for your fortune, and approve the tool call when prompted. You should get back a fortune generated by your own tool.\n\nOnce the basics work, adding more tools is just a matter of writing another function and decorating it with `@mcp.tool`\n\n:\n\nIf things get heavier — image generation, larger-scale analysis — you don't have to run this on your laptop. You could offload the compute to a GPU cloud instance and expose the MCP server from there instead.\n\nWith FastMCP, building an MCP server comes down to \"write a Python function, add `@mcp.tool`\n\n.\" We walked through the whole loop here — environment setup, writing the tool, connecting it to Claude Code, and confirming it works — using a fortune-telling tool as the example.\n\nThe same pattern scales to far more useful things: wrapping internal tools, automating repetitive tasks, and more. Fortune-telling is just the toy example — try swapping in your own idea next.\n\n📌 This post reflects Claude Code's behavior as of June 2026. Since Claude Code updates frequently, check the\n\n[official docs]for the latest details.\n\n*This article was edited with AI assistance.\n*Originally published in Japanese on EdgeHUB.*", "url": "https://wpnews.pro/news/building-a-custom-mcp-server-for-claude-code-a-fortune-telling-tool-with-fastmcp", "canonical_source": "https://dev.to/_02121fbe984480fd65fc/building-a-custom-mcp-server-for-claude-code-a-fortune-telling-tool-with-fastmcp-2j0d", "published_at": "2026-08-13 15:04:18+00:00", "updated_at": "2026-08-13 15:19:33.352358+00:00", "lang": "en", "topics": ["developer-tools", "artificial-intelligence", "large-language-models"], "entities": ["FastMCP", "Claude Code", "MCP", "Python"], "alternates": {"html": "https://wpnews.pro/news/building-a-custom-mcp-server-for-claude-code-a-fortune-telling-tool-with-fastmcp", "markdown": "https://wpnews.pro/news/building-a-custom-mcp-server-for-claude-code-a-fortune-telling-tool-with-fastmcp.md", "text": "https://wpnews.pro/news/building-a-custom-mcp-server-for-claude-code-a-fortune-telling-tool-with-fastmcp.txt", "jsonld": "https://wpnews.pro/news/building-a-custom-mcp-server-for-claude-code-a-fortune-telling-tool-with-fastmcp.jsonld"}}