{"id":26426476,"url":"https://github.com/simonberner/mcp-server-calculator","last_synced_at":"2025-10-07T06:49:20.878Z","repository":{"id":282766232,"uuid":"949587664","full_name":"simonberner/mcp-server-calculator","owner":"simonberner","description":"Demo of a local running MCP Server","archived":false,"fork":false,"pushed_at":"2025-04-21T13:06:08.000Z","size":68,"stargazers_count":0,"open_issues_count":1,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-06-18T01:41:53.389Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/simonberner.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2025-03-16T19:27:28.000Z","updated_at":"2025-05-09T11:45:18.000Z","dependencies_parsed_at":null,"dependency_job_id":"093c7997-d55e-43b1-9aa4-56bd417d7b51","html_url":"https://github.com/simonberner/mcp-server-calculator","commit_stats":null,"previous_names":["simonberner/mcp-server-calculator"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/simonberner/mcp-server-calculator","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/simonberner%2Fmcp-server-calculator","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/simonberner%2Fmcp-server-calculator/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/simonberner%2Fmcp-server-calculator/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/simonberner%2Fmcp-server-calculator/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/simonberner","download_url":"https://codeload.github.com/simonberner/mcp-server-calculator/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/simonberner%2Fmcp-server-calculator/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":278734406,"owners_count":26036404,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-10-07T02:00:06.786Z","response_time":59,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2025-03-18T03:31:58.132Z","updated_at":"2025-10-07T06:49:20.873Z","avatar_url":"https://github.com/simonberner.png","language":"Python","funding_links":[],"categories":["🤖 AI/ML","Math and Statistics"],"sub_categories":[],"readme":"# How to build an MCP server - Calculator Example\n\n[![smithery badge](https://smithery.ai/badge/@simonberner/mcp-server-calculator)](https://smithery.ai/server/@simonberner/mcp-server-calculator)\n[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://github.com/simonberner/mcp-server-calculator/blob/main/LICENSE)\n\n## About\n\nThis is a very simple example of how to build an MCP server that provides basic math operations to an MCP client.\n\n### What is MCP?\n\nModel Context Protocol (MCP) is a protocol that enables LLMs to access custom tools and services. An MCP client can make requests to MCP servers to access tools that they provide. This example represents a simple calculator server that provides basic math operations to a client.\n\n\u003e \"MCP can provide a single, standardized way for AI models to interact with external systems. You write code once and all AI systems can use it.\" [1](#resources)\n\n\u003e \"Servers are the fundamental building block that enriches LLMs with external data and context.\" [2](#resources)\n\n![Chat MCP Calculator](./chat-mcp-calculator.webp)\n\n## Tech Stack\n\n- Python3\n- Pytest\n- MCP SDK\n- MCP CLI\n- Nix (optional)\n\n## How to setup and use\n\n### Smithery\n\nTo install mcp-server-calculator for Claude Desktop automatically via [Smithery](https://smithery.ai/server/@simonberner/mcp-server-calculator):\n\n```bash\nnpx -y @smithery/cli install @simonberner/mcp-server-calculator --client claude\n```\n\n### Development Setup\n\nAs we are using Nix in this project for having a reproducible and isolated development environment, there is no need to install Python or any other dependencies. You will get everything you need out of the box. Also there is no need to create a virtual environment in Python using `venv` or `poetry`, but you have to be willing to install Nix on your system.\n\n- Install [direnv](https://github.com/direnv/direnv) (used to load the development environment)\n- Install [Lix](https://lix.systems/install/)\n- Clone this repository\n- cd into the directory\n- Run `direnv allow`\n- Run `pytest`\n\n### Alternative\n\nIf you don't want to take the Smithery or the Nix route, you can of course also use [uv](https://docs.astral.sh/uv/) to build the package/project. Here is some guidance:\n\n```shell\n# Install uv (see https://docs.astral.sh/uv/getting-started/installation/)\ncurl -LsSf https://astral.sh/uv/install.sh | sh\n\n# Create a virtual environment named .venv\nuv venv\n\n# Activate the virtual environment (example for bash/zsh)\nsource .venv/bin/activate\n\n# Now run the install or build commands\nuv pip install -e .\n# or\nuv pip wheel . -w dist\n```\n\n### Running \u0026 Testing the Server locally\n\n- [MCP Inspector](https://modelcontextprotocol.io/docs/tools/inspector) is a handy GUI tool that lets you test your custom MCP server via web interface at http://localhost:5173 without integrating it with LLM / AI agents.\n\n```shell\nmcp dev src/mcp_server_calculator/calculator.py\n```\n\n### Host/Client integration\n\n- Add the following to your mcp config:\n\n```json\n{\n  \"mcpServers\": {\n    \"calculator\": {\n      \"command\": \"python\",\n      \"args\": [\n        \"\u003cYOUR-PATH\u003e/mcp-server-calculator/src/mcp_server_calculator/calculator.py\"\n      ]\n    }\n  }\n}\n```\n\n### Notes\n\n- When using [Windsurf IDE](https://codeium.com/windsurf) as MCP Host, you need to have a [Pro Plan](https://codeium.com/pricing) to be able to use Cascade (as MCP Client) with MCP Servers.\n\n## Issues\n\nCheck [Issues](https://github.com/simonberner/mcp-server-calculator/issues) for seeing the current issues or for opening a new one.\n\n## Resources\n\n- [1] [MCP server: A step-by-step guide to building from scratch](https://composio.dev/blog/mcp-server-step-by-step-guide-to-building-from-scrtch/)\n- [2] [What is Model Context Protocol (MCP)?](https://composio.dev/blog/what-is-model-context-protocol-mcp-explained/)\n- [Understanding MCP and how AI engineers can leverage it](https://dev.to/luxdevhq/understanding-mcp-and-how-ai-engineers-can-leverage-it-3e2i`)\n- [MCP SDK](https://pypi.org/project/mcp/)\n- [MCP CLI](https://pypi.org/project/mcp-cli/)\n- [MCP Inspector](https://github.com/modelcontextprotocol/inspector)\n- [The largest collection of MCP Servers](https://mcp.so/)\n- [A Beginner's Guide to using MCP](https://youtu.be/Y_kaQmhGmZk)\n- [Claude MCP has Changed AI Forever - Here's What You NEED to Know](https://www.youtube.com/watch?v=v_6EXt6T83I)\n- [Find MCP servers](https://windsurf.run/mcp)\n- [Build your first MCP server with TypeScript in under 10 minutes](https://hackteam.io/blog/build-your-first-mcp-server-with-typescript-in-under-10-minutes/)\n- [Model Context Protocol (MCP) Introduction](https://modelcontextprotocol.io/introduction)\n\n## Credits\n\n- Nix-Setup taken from [ical2json](https://github.com/CodersOnlyCH/ical2json)\n\n## Nice things to know\n\n### Nix\n\n- [Why using Nix?](https://nixos.org/)\n- [Why using Lix?](https://lix.systems/about/#why-lix)\n- [Nix packages](https://search.nixos.org/packages)\n- [nix-shell](https://nix.dev/manual/nix/2.26/command-ref/nix-shell.html)\n\n### Cloudflare\n\n- [Build a Remote MCP server](https://developers.cloudflare.com/agents/guides/remote-mcp-server/)\n- [Wrangler configuration](https://developers.cloudflare.com/workers/wrangler/configuration/)","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsimonberner%2Fmcp-server-calculator","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fsimonberner%2Fmcp-server-calculator","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsimonberner%2Fmcp-server-calculator/lists"}