Skip to content

Instantly share code, notes, and snippets.

@gabriel1l

gabriel1l/av-mcp-server-codex.md

Created October 29, 2025 18:58
Show Gist options

  • Select an option

    Learn more about clone URLs
  • Save gabriel1l/6d3777995e56b2bef57cf1e99974d80e to your computer and use it in GitHub Desktop.

Select an option

Learn more about clone URLs
Save gabriel1l/6d3777995e56b2bef57cf1e99974d80e to your computer and use it in GitHub Desktop.
Download ZIP
Step-by-step setup guide for connecting Codex to the Alpha Vantage MCP Server on macOS. Includes installation commands for Node, Homebrew, VS Code, and Codex CLI, configuration examples, troubleshooting notes, and a demo workflow for generating financial applications end-to-end — no coding required. #AlphaVantage #Codex #MCPServer #NoCode #Setup…
Raw
av-mcp-server-codex.md

🚀 Codex CLI + Alpha Vantage MCP Setup (macOS)

This guide walks you through setting up OpenAI Codex CLI from a fresh macOS VM, connecting it to the Alpha Vantage MCP server.

💡 At least 64 GB storage is recommended for fresh VMs.

📦 Homebrew is used for installing packages.

📝 VS Code is used for file editing.

You can use your preferred package manager and file editor, but note that commands and syntax may differ from the examples in this guide.

🧰 1. Install your preferred macOS Package Manager and File Editor

📦 macOS Package Manager for this demo: Homebrew

Homebrew is used in this demo to install packages.

To install Homebrew via Terminal, run the following:

/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

⚠️ If your install fails due to insufficient storage, download and extract the latest .pkg from Homebrew’s releases page. Homebrew's final footprint is only ~3 GB, but installation can temporarily require 25+ GB on top of the 11+ GB occupied by macOS itself on a fresh install.

At the end of the Homebrew install, copy-paste the commands generated by the installer to activate Homebrew without restarting your Terminal.

# The below commands are illustrative. Homebrew will replace 'your-username'.
echo >> /Users/your-username/.zprofile
echo 'eval "$(/opt/homebrew/bin/brew shellenv)"' >> /Users/your-username/.zprofile
eval "$(/opt/homebrew/bin/brew shellenv)"

Verify installation:

brew -v

📝 File Editor for this demo: VS Code

VS Code is used in this demo for file editing. If you don't already have VS Code installed, install with Homebrew:

brew install --cask visual-studio-code

🧩 Enable the code command in Terminal

The code command lets you open files and folders directly in VS Code from the Terminal. To enable it:

  1. Open VS Code (either manually or type open -a "Visual Studio Code" in Terminal)
  2. Press Cmd(⌘) + Shift + P
  3. Search for “Shell Command: Install 'code' command in PATH”
  4. Press Enter

💡 Tip: You can also open this .md file in VS Code for a cleaner, formatted view.

  1. Open this .md file in VS Code.
  2. Press Cmd(⌘) + Shift + V to preview the Markdown.

⚙️ 2. Install Node.js and npm

Codex CLI (which will be installed in the next section) runs on Node.js, so install it using Homebrew:

brew install node

Verify installation by checking the versions:

node -v
npm -v

🧩 3. Install Codex CLI

Install Codex CLI.

npm install -g @openai/codex

Or, update:

npm update -g @openai/codex

Verify version (0.34 or later to avoid compatibility issues):

codex --version

🧠 4. Install uv (Modern Python Environment Manager)

uv is used to run the Alpha Vantage MCP server directly via uvx, without needing a separate proxy installation.

curl -LsSf https://astral.sh/uv/install.sh | sh

Add it to your PATH to avoid restarting shell. This command should also appear in the Terminal (commands for sh, bash, zsh):

source "$HOME/.local/bin/env"

Confirm installation:

uv --version

📁 5. Configure Codex

Create a configuration directory and file:

code ~/.codex/config.toml # 'code' will open in VS Code; replace 'code' with your preferred editor.

Paste the following (replace YOUR_API_KEY with your Alpha Vantage API key):

[mcp_servers.alphavantage]
command = "uvx"
args = ["av-mcp", "YOUR_API_KEY"]

Save and close the file.

🧱 6. (Recommended) Create a Project Directory

Create a project directory for Codex-generated projects. You can replace codex-projects with any folder name you prefer. (Tip: ~ refers to your home directory; you can specify a full path if preferred.)

mkdir -p ~/codex-projects
cd ~/codex-projects

🧭 7. Run Codex CLI

Launch Codex CLI from your project directory.

codex

First time users will be guided through additional prompts.

Then, type the following as a prompt into Codex to connect to Alpha Vantage MCP:

/mcp

👏 Installation complete!

You now have a fully working Codex + Alpha Vantage setup on macOS.

Continue with the below instructions for a demo.

8. Paste ONE of these prompts into Codex.

Recommendation: use the detailed prompt for consistency and reliability.

--- Simple Prompt (quick start) ---

Build a simple stock portfolio tracker web app using Alpha Vantage MCP.

Use TIME_SERIES_DAILY from the Alpha Vantage MCP Server.

It should fetch live data for 3 tech stocks, display portfolio value over time, and run locally with Node.js. Save it in a folder called “portfolio-tracker”.

--- Detailed Prompt (recommended) ---

Build a Portfolio Tracker web app that runs locally on localhost. Use the Alpha Vantage MCP server to fetch stock data.

Use TIME_SERIES_DAILY from the Alpha Vantage MCP Server.

Requirements Assets / Allocation

  • Track the top 3 major tech stocks
  • Assume a total portfolio value ≈ $200,000 at today’s prices.
  • Distribute the value unevenly across the three stocks (not equal thirds).

Data

  • Fetch historical daily data for the past 6 months for each stock.
  • Implement a fallback cache:
    • If a live MCP API call fails, load from cached JSON.
    • Mark cached data clearly by appending “(cached)” to that stock’s legend entry.

Visualizations

  1. Line chart:
  • Toggle between total portfolio value over time and individual stock values over time.
  1. Stacked Area Chart:
  • Show allocation percentages (per stock) over time.
  • Add total portfolio value as a secondary Y-axis line.

Other

  • Save project in subdirectory called “portfolio-tracker”
  • Create a .env file to put in my api key
  • Leverage npm start and npm install to launch the web app

9. In a 2nd terminal, verify the project folder and generated files.

ls                # look for "portfolio-tracker"
cd portfolio-tracker
ls                # confirm files were created

10. Follow the instructions given by Codex to run the app locally.

Setup Example: Setup .env with your API key, then run the app.

cd portfolio-tracker
cp .env.example .env
code .env        # paste in your API key

Run Example 1: Install dependencies and start the dev server.

npm install
npm start         # open the URL (e.g., http://localhost:3000) in your browser

Run Example 2: Run with Node directly.

node server.js

Tip: If errors occur, paste error messages back into Codex. Codex can often generate fixes.

Note: Free Alpha Vantage API keys have daily call limits.

Some APIs require a Premium key. Notably, TIME_SERIES_DAILY_ADJUSTED is a premium API; use TIME_SERIES_DAILY instead.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment