# To Do List MCP

A minimal [Model Context Protocol](https://modelcontextprotocol.io) server that exposes a
personal to-do list backed by SQLite. Built with the official Python
[`mcp`](https://pypi.org/project/mcp/) SDK.

## Tools

| Tool            | Description                                             | Arguments                                                          |
| --------------- | -------------------------------------------------------- | ------------------------------------------------------------------- |
| `task_add`      | Add a task, or a list of tasks in one call               | `task_name: str \| list[str]`                                       |
| `task_get`      | List all incomplete tasks                                 | —                                                                    |
| `task_update`   | Rename a task and/or set its status                       | `task_id: int`, `task_name: str`, `task_status: bool = False`       |
| `task_complete` | Mark a task complete                                       | `task_id: int`                                                      |

Tasks are stored in `todolist.db` (SQLite), created automatically on first run in the
server's working directory.

## Requirements

- Python >= 3.13
- [uv](https://docs.astral.sh/uv/)

## Installation

Clone the repo and install dependencies with uv:

```bash
uv sync
```

## Usage

### Claude Desktop

Add the server to your `claude_desktop_config.json` (Claude menu → Settings →
Developer → Edit Config), or install it automatically with the MCP CLI:

```bash
uv run mcp install src/to_do_list_mcp/server.py --name "To Do List"
```

This adds an entry like the following:

```json
{
  "mcpServers": {
    "To Do List": {
      "command": "uv",
      "args": [
        "run",
        "--with",
        "mcp[cli]",
        "mcp",
        "run",
        "/absolute/path/to/to_do_list_mcp/src/to_do_list_mcp/server.py"
      ]
    }
  }
}
```

Restart Claude Desktop afterwards for the server to be picked up.

### Development

Run the server directly with the MCP Inspector for interactive testing:

```bash
uv run mcp dev src/to_do_list_mcp/server.py
```

## License

No license specified.