# Basic MCP Server

A small [MCP](https://modelcontextprotocol.io) server built with the official
Python SDK (`mcp` 2.x). It exposes four tools that let an MCP client
(Claude Desktop, the MCP Inspector, etc.) work with the local file system,
run shell commands, and fetch web pages.

## Tools

| Tool | Description | Parameters |
| --- | --- | --- |
| `file_reader` | Reads the file at the specified path. | `path` |
| `write_new_file` | Creates a new file and writes the given content into it. Overwrites the file if it already exists. | `path`, `content` |
| `execute_command` | Runs the given shell command and returns its output (stdout + stderr). | `command`, `timeout` (seconds, default 30) |
| `fetch_url` | Fetches a URL with an HTTP GET request and returns the status code and the page source. | `url`, `timeout` (seconds) |

All tools return plain strings. Failures are prefixed with `ERROR:`, successful
writes with `INFO:`.

> **Warning:** `execute_command` runs arbitrary shell commands with the
> permissions of the user running the server. Only connect clients you trust.

## Requirements

- Python 3.10 or newer
- [`mcp`](https://pypi.org/project/mcp/) 2.x and [`requests`](https://pypi.org/project/requests/) 2.x (see `requirements.txt`)

## Installation

```bash
python -m venv venv
source venv/bin/activate        # Windows: venv\Scripts\activate
pip install -r requirements.txt
```

## Usage

Run the server with the MCP Inspector (browser-based debugging UI):

```bash
mcp dev server.py
```

Run the server directly over stdio:

```bash
mcp run server.py
```

Install the server into the Claude Desktop app:

```bash
mcp install server.py
```

The server object is named `mcp` in `server.py`, so the CLI commands above
find it automatically.

## Project layout

```
server.py           # the MCP server and its tools
requirements.txt    # dependencies
LICENSE             # MIT license
```

## License

[MIT](LICENSE)