Todo

You can manage your Todo list through a fast FastAPI API and an MCP server that lets Gemini CLI control and query tasks. This MCP setup enables you to run the API and its MCP endpoint locally, then use Gemini to interact with your Todo data through natural language commands, making it easy to create, view, update, and delete tasks and to retrieve statistics at a glance.

How to use

Connect your Gemini CLI to the MCP server to manage todos with natural language. You will run two servers locally: the FastAPI application and the MCP server. Gemini can then send commands like listing all tasks, querying statistics, creating new todos, updating statuses, and deleting tasks.

Configure Gemini to connect to the MCP server by providing the MCP connection details shown in the example configuration. This enables Gemini to issue the supported tools to the MCP server and receive structured results.

Key actions you can perform through the MCP interface include listing all todos, retrieving statistics, creating a new task, updating an existing task, deleting a task, and getting details for a specific task. The MCP server exposes these capabilities as distinct tools that your Gemini CLI can invoke.

{
  "mcpServers": {
    "todo-mcp-server": {
      "command": "python3",
      "args": ["mcp_server.py"],
      "cwd": "/home/okki/Desktop/projects/fast-apimcp"
    }
  }
}

How to install

Prerequisites: you need Python installed on your system and access to a terminal or command prompt.

Step 1: Install the dependencies for the project.

pip install -r requirements.txt

Step 2: Start the FastAPI server to serve the Todo API.

python main.py

Step 3: Start the MCP server in a separate terminal to enable Gemini CLI control.

python mcp_server.py

Step 4: (Optional) Update the Gemini configuration to point to your MCP server using the example settings.

{
  "mcpServers": {
    "todo-mcp-server": {
      "command": "python3",
      "args": ["mcp_server.py"],
      "cwd": "/home/okki/Desktop/projects/fast-apimcp"
    }
  }
}

Additional content

This setup includes a pre-loaded set of five dummy todos to help you test and explore functionality quickly. The MCP server exposes a set of tools that map to common CRUD operations and a stats endpoint, allowing you to monitor progress and task status with ease.

If you need to test individual endpoints directly from the command line, you can query the FastAPI endpoints for behavior and data, such as listing all tasks or retrieving statistics, to verify that both servers are operating in concert.

Troubleshooting tips include ensuring both servers are running, verifying the MCP configuration in your Gemini setup, and checking that the required Python packages are installed. If port conflicts occur, adjust the startup commands or ports in your run configuration.

The project uses FastAPI for the HTTP API, an MCP server implementation for Gemini interaction, and FastMCP as the bridging library. You can extend the list of todos, add new stats calculations, and experiment with additional Gemini-driven commands as you grow your task management workflow.

Available tools

get_todos

Retrieve all todos from the API via the MCP server, returning the full list of tasks with their IDs, titles, descriptions, and statuses.

get_todo_stats

Return a summary of tasks including total, completed, and pending counts, along with a completion percentage.

create_todo

Create a new todo with a title and optional description, returning the created task details.

update_todo

Update an existing todo by ID, allowing changes to title, description, or status.

delete_todo

Delete a todo by its ID from the data store.

get_todo_by_id

Fetch details for a single todo by its ID.