# Sampledotnetmcpserver

> Sampledotnetmcpserver is an open-source MCP server for agent tooling. Reference .NET MCP server with sample weather, greeting and random number tools. It runs locally on your machine and is started by your AI client.

- **Kind:** MCP server
- **Pricing:** Open source
- **Platforms:** vscode, CLI, Windows, macOS, Linux, API
- **Repository:** https://github.com/timheuer/sampledotnetmcpserver
- **MCP Registry name:** io.github.timheuer/sampledotnetmcpserver
- **Categories:** [agent tooling](https://ai-powered.com/categories/agent-tooling)
- **Listing updated:** 2026-11-18

## About

The README describes this repository as a teaching sample for building a Model Context Protocol server in C# with the ModelContextProtocol SDK. It shows how tools are implemented, registered and wired to a stdio transport, so the code is meant to be read and copied from rather than deployed as a finished service.

The server ships a handful of example tools: a random number generator, hello and goodbye greetings, and two weather tools that look up current conditions and multi-day forecasts by US zip code. The weather lookups use the wttr.in API. It is packaged as a NuGet package and can be run from source with dotnet run or installed from NuGet.org in editors that support MCP.

The project suits .NET developers who want a worked example of MCP packaging and publishing, including CI-driven NuGet releases with Nerdbank.GitVersioning. The README states it is for demonstration and reference purposes only.

## Features

- **Stdio MCP transport:** Runs as a local process that communicates with MCP clients over standard input and output.
- **Sample weather tools:** Provides current weather and multi-day forecast lookups for US zip codes via wttr.in.
- **Random number generator:** Returns a random integer within a requested range.
- **Greeting tools:** Includes simple hello and goodbye tools that take a name.
- **NuGet packaging example:** Shows how to package and publish an MCP server as a NuGet package.
- **Editor configuration examples:** Includes JSON snippets for running the server from source or from NuGet.org.

## Good for

- Learning how to structure tools in a C# MCP server
- Testing an MCP client in VS Code or Visual Studio with simple tools
- Using a template for publishing a .NET MCP server to NuGet
- Checking weather or forecasts by US zip code from a chat assistant

## Install

### Claude Code (Terminal)

```sh
claude mcp add sampledotnetmcpserver -- dnx TimHeuer.SampleDotnetMcpServer --yes
```

### Claude Desktop (claude_desktop_config.json)

```json
{
  "mcpServers": {
    "sampledotnetmcpserver": {
      "command": "dnx",
      "args": [
        "TimHeuer.SampleDotnetMcpServer",
        "--yes"
      ]
    }
  }
}
```

### Cursor (~/.cursor/mcp.json)

```json
{
  "mcpServers": {
    "sampledotnetmcpserver": {
      "command": "dnx",
      "args": [
        "TimHeuer.SampleDotnetMcpServer",
        "--yes"
      ]
    }
  }
}
```

### VS Code (.vscode/mcp.json)

```json
{
  "servers": {
    "sampledotnetmcpserver": {
      "type": "stdio",
      "command": "dnx",
      "args": [
        "TimHeuer.SampleDotnetMcpServer",
        "--yes"
      ]
    }
  }
}
```

### Windsurf (~/.codeium/windsurf/mcp_config.json)

```json
{
  "mcpServers": {
    "sampledotnetmcpserver": {
      "command": "dnx",
      "args": [
        "TimHeuer.SampleDotnetMcpServer",
        "--yes"
      ]
    }
  }
}
```

### Other clients (your client's MCP settings (most use this shape))

```json
{
  "mcpServers": {
    "sampledotnetmcpserver": {
      "command": "dnx",
      "args": [
        "TimHeuer.SampleDotnetMcpServer",
        "--yes"
      ]
    }
  }
}
```

## Tools

- `get_random_number`: Generates random numbers within a specified range.
- `say_hello_name`: Simple greeting tool.
- `say_goodbye_name`: Simple farewell tool.
- `get_weather_by_zip_code`: Gets current weather for a US zip code.
- `get_weather_forecast`: Gets a multi-day weather forecast for a US zip code.

## FAQ

### Is this meant for production use?

No. The README says the project is for demonstration and reference purposes only.

### What transport does the server use?

It uses the stdio transport.

### Which weather service does it call?

The weather tools use the wttr.in API.

### How can I install it from NuGet?

The README gives an example configuration that runs the package with dnx and a version argument, to be used in an IDE's MCP settings.

### Is Sampledotnetmcpserver free?

Yes. Sampledotnetmcpserver is open source, so you can use and self-host it for free.

### How do I add Sampledotnetmcpserver to Claude Code?

Run this command in your terminal: claude mcp add sampledotnetmcpserver -- dnx TimHeuer.SampleDotnetMcpServer --yes

## Where this comes from

- Description: written from the project's README and its MCP Registry entry.
- Install steps: from the official MCP Registry entry.

## Alternatives

- [MCP Quickstart](https://ai-powered.com/mcp/mcp-quickstart): MCP Quickstart is an open-source MCP server for agent tooling.

---
Source: https://ai-powered.com/mcp/sampledotnetmcpserver
