derailed-dash/aoc-utils-mcp
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
- Advent of Code
- Dazbo's Advent of Code Walkthroughs
- FastMCP Quickstart
- FastMCP Cloud
- Gemini CLI with FastMCP
- FastMCP Gemini Integration
- Dazbo's Advent of Code Solutions Repo
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
And it has saved the file!
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:
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>