aoc-utils-mcp

derailed-dash/aoc-utils-mcp

3.2

If you are the rightful owner of aoc-utils-mcp and would like to certify it and/or have it hosted online, please leave a comment on the right or send an email to henry@mcphub.com.

The Aoc-Utils MCP Server provides Advent of Code utilities through an MCP server, facilitating access to puzzle data for specific years and days.

The Aoc-Utils MCP Server and Gemini Extension

This repo contains an extension and MCP server that exposes handy Advent of Code (AoC) utilities, e.g.

  • The get_puzzle_input(year: int, day: int) retrieves your puzzle data for a given specific year and day.

It also acts as a useful example of how to implement a FastMCP server for Python functions, and explains how to integrate the MCP server into an AI tool like Gemini CLI.

Useful Links

Demo from Gemini CLI

My prompt to Gemini CLI:

Fetch the input data for AoC 2022 day 1, and save to tmp/aoc_2022_day1_input.txt

Get AoC Input

And it has saved the file!

File Saved

Development

Running the MCP Server

Pre-reqs for development and running locally:

# Create venv and activate
uv sync
source .venv/bin/activate

Then launch the server.

Note that the fastmcp CLI automatically integrates with uv to manage environments and dependencies.

cd mcp-server/src

# PRE-REQ: Ensure AOC_SESSION_COOKIE is set as env var
export AOC_SESSION_COOKIE=<session key>

# To launch the server with default stdio transport
fastmcp run my_server.py

# Or to run with HTTP transport:
fastmcp run server.py --transport http --port 9000

# Or if we just configure using the `fastmcp.json`, we don't need any parameters:
fastmcp run # If fastmcp.json is in the cwd
fastmcp run path/to/fastmcp.json
fastmcp run prod.fastmcp.json # use a specific json

Check it's healthy.

Note that command-line arguments override the fastmcp.json configuration.

Testing

We can test two ways:

Unit Testing

Use the make test shortcut.

With the Sample Client

Run a separate terminal session, and from there:

# Activate the venv
source .venv/bin/activate

# Launch a client with Python - requires server to be HTTP
python3 tests/a_client.py 

Installing into Gemini CLI

Installing as an Extension

# Install from the GitHub URL
gemini extensions install https://github.com/derailed-dash/aoc-utils-mcp

Note that you can enable and disable extensions at global (user) and workspace level. This is configured in ~/.gemini/extensions/extension-enablement.json. For example, to enable this extension only in a specific workspace:

{
  "adk-docs-ext": {
    "overrides": [
      "/home/darren/*"
    ]
  },
  "gcloud": {
    "overrides": [
      "/home/darren/*"
    ]
  },
  "aoc-utils": {
    "overrides": [
      "!/home/darren/*",
      "/home/darren/localdev/python/advent-of-code/*"
    ]
  }
}

We can see that the aoc-utils extension is disabled (!) at global level, but enabled in the advent-of-code workspace.

Installing the MCP Server Only

I struggled to install with either of these approaches:

# Using FastMCP CLI, which automatically calls the Gemini CLI MCP management system
# It runs gemini mcp add for you
fastmcp install gemini-cli server.py \
  --project /path/to/your/project \
  --env AOC_SESSION_COOKIE=$AOC_SESSION_COOKIE

# Using `gemini mcp add`
gemini mcp add aoc-utils-mcp \
  uv -- run --project /path/to/project --with fastmcp fastmcp run server.py \
  -e AOC_SESSION_COOKIE=$AOC_SESSION_COOKIE

So instead, I just create this entry in my settings.json, in my AoC project:

{
  "mcpServers": {
    "aoc-utils-mcp": {
      "command": "uv",
      "args": [
        "run",
        "--with",
        "fastmcp",
        "fastmcp",
        "run",
        "/home/darren/localdev/python/aoc-utils-mcp/src/server.py"
      ],
      "env": {
        "AOC_SESSION_COOKIE": "${AOC_SESSION_COOKIE}"
      },
      "cwd": "/home/darren/localdev/python/aoc-utils-mcp/src"
    }
  }
}

Note: You need to ensure your AOC_SESSION_COOKIE environment is set before launching Gemini CLI.

We can check the MCP server is running in Gemini CLI:

MCP server running

Appendix

Deploying to FastMCP Cloud

We can optionally deploy the sever to FastMCP Cloud to make it publicly accessible. Note that FastMCP Cloud automatically detects and uses pyproject.toml.

Troubleshooting

Terminating the Background Process

If we're having trouble closing the background process...

pgrep -f "fastmcp"
kill <PID>