Current version: 0.1.6
CodexMCP is a service that gives your applications access to AI coding capabilities without needing to build complex integrations. It's a server that exposes powerful code-related AI tools through a simple, standardized API.
Important: CodexMCP is not an autonomous agent - it's a tool provider that responds to specific requests. Your application remains in control, making specific requests for code generation, refactoring, or documentation as needed.
Think of CodexMCP as a bridge between your application and OpenAI's powerful AI coding capabilities. You send structured requests to the server (like "generate Python code that sorts a list"), and it returns the requested code or documentation.
A minimal FastMCP server wrapping the OpenAI Codex CLI to provide AI code generation, refactoring, and documentation capabilities through a standardized API.
CodexMCP has been enhanced with several key improvements:
The latest update enables real-time streaming of responses when using the OpenAI API. This provides immediate feedback as tokens are generated, significantly improving the user experience for all tools.
The latest update removes the long-lived CodexPipe in favor of per-call CLI execution, improving reliability and simplifying the architecture. All tools now route through a new dedicated cli_backend module.
The tools API has been reorganized for clarity and ease of use, with a focus on the most essential coding tasks:
code_generate: Unified entry point for all code-generation tasks.review_code: Assess code quality, security, style or other aspects.describe_codebase: Explain the repository, a file, or a code snippet.
The describe_codebase tool (when provided a file path) allows you to analyze code with awareness of its surrounding context.
The code_generate tool, when provided with feedback or an iteration count, enables an iterative approach to code generation, where you can provide feedback on previous iterations to refine the results.
The review_code tool provides detailed code quality assessments with actionable suggestions for improvement, focusing on specific areas like performance, readability, or security.
The describe_codebase tool provides code explanations tailored to different audiences (developers, managers, beginners) with customizable detail levels.
Functionality for code migration and modernization can be achieved using code_generate with appropriate descriptions.
The code_generate tool, when provided a template_name and parameters, enables code generation using customizable templates, increasing productivity for common tasks.
-
Prerequisites:
-
Node.js 18 LTS or later
-
Python 3.10 or later
-
Codex CLI installed globally:
npm install -g @openai/codex
Note: If you don't have access to the Codex CLI, you can still use CodexMCP with the OpenAI API fallback (see Python-only fallback below).
-
-
Install CodexMCP:
pip install codexmcp
Optional (test dependencies):
pip install codexmcp[test]
-
(Optional) Python-only fallback
If you don't want to install the Node-based Codex CLI you can instead install the OpenAI Python SDK extra:
# installs codexmcp + openai pip install "codexmcp[openai]"
Make sure
OPENAI_API_KEYis set in your environment or.envfile. At runtime CodexMCP will automatically fall back to the OpenAI ChatCompletion API whenever thecodexexecutable cannot be found. -
Environment Setup:
-
Create a
.envfile in your project root. -
Add your OpenAI API key:
OPENAI_API_KEY=sk-your-key-here -
Optional environment variables:
CODEXMCP_DEFAULT_MODEL: Default model to use (default: "o4-mini").CODEXMCP_LOG_LEVEL: Logging level (default: INFO).CODEXMCP_CONSOLE_LOG: Enable console logging (default: true).CODEXMCP_CACHE_ENABLED: Enable response caching (default: true).CODEXMCP_CACHE_TTL: Cache time-to-live in seconds (default: 3600).CODEXMCP_MAX_RETRIES: Maximum retry attempts for API calls (default: 3).CODEXMCP_RETRY_BACKOFF: Exponential backoff factor for retries (default: 2.0).CODEXMCP_USE_CLI: Whether to use Codex CLI when available (default: true).
-
Start the CodexMCP server with one simple command:
python -m codexmcp.serveror use the convenient entry point:
codexmcpThe server will start listening on port 8080 (by default). Your applications can now make requests to the server's API endpoints.
If you're developing or extending CodexMCP, be aware of these implementation details:
-
Prompt Templates: All prompt templates are stored in the
src/codexmcp/prompt_files/directory and are loaded lazily when first needed. If you want to add custom templates, add.txtfiles to this directory. -
o4-mini Model Support: The system has special handling for the
o4-minimodel, including proper configuration ofmax_completion_tokensand temperature settings (temperature is always set to 1.0 for o4-mini). -
CLI Integration: As of version 0.1.6, CodexMCP now uses a dedicated
cli_backendmodule for all Codex CLI interactions, executed per-call rather than through a long-lived pipe. This improves reliability and simplifies the architecture. -
Custom Templates: To add custom templates, place them in
src/codexmcp/templates/with a.txtextension. Templates use Python's standard string formatting with named placeholders like{parameter_name}.
- Your Application makes a request to a specific CodexMCP endpoint (like
/tools/generate_code) - CodexMCP Server processes the request and sends it to the Codex CLI
- Codex CLI generates the requested code or documentation with filesystem context awareness
- CodexMCP Server returns the result to your application
This approach gives you the power of AI coding assistance while keeping your application in control of when and how to use it.
CodexMCP provides the following AI-powered tools:
-
code_generate: Unified entry point for all code-generation tasks.description: Task description.language: (Optional) Programming language (default: "Python").template_name: (Optional) Name of the template to use.parameters: (Optional) Dictionary of parameters to fill in the template.feedback: (Optional) Feedback on previous iterations.iteration: (Optional) Current iteration number (default: 1).
-
describe_codebase: Explain the repository, a file, or a code snippet.subject: (Optional) Code snippet, file path, or concept to explain. If omitted, describes the current repository.audience: (Optional) Target audience (default: "developer").detail_level: (Optional) Level of detail (e.g., "brief", "medium", "detailed", default: "medium").
-
review_code: Assess code quality, security, style or other aspects.code: (Optional) Source code to assess. If omitted, the CLI might analyze the workspace based on the prompt.language: (Optional) Programming language (default: "Python").focus_areas: (Optional) List of areas to focus on (e.g., "security", "performance").extra_prompt: (Optional) Free-form instructions to guide the review.
All tools leverage the filesystem context awareness of the Codex CLI when it's used, allowing them to work with the current project's files and directory structure. The model parameter can be passed to any tool to specify the OpenAI model to use (default: "o4-mini" or as configured).
import asyncio
from fastmcp import MCPClient
async def main():
# Ensure the server is running, e.g., by `python -m codexmcp.server`
# or the `codexmcp` command.
client = MCPClient("http://localhost:8080") # Default port
# Generate some Python code
generated_code = await client.code_generate(
description="Create a function to calculate Fibonacci numbers recursively",
language="Python"
)
print("Generated code:")
print(generated_code)
# Review the generated code
quality_assessment = await client.review_code(
code=generated_code,
language="Python",
focus_areas=["readability", "potential bugs"],
extra_prompt="Consider Python best practices."
)
print("\nCode quality assessment:")
print(quality_assessment)
# Describe the generated code
explanation = await client.describe_codebase(
subject=generated_code, # Can also be a file path or general concept
audience="beginner",
detail_level="detailed"
)
print("\nCode explanation for beginners:")
print(explanation)
# Example: Generate code from a template
# First, ensure you have a template, e.g., src/codexmcp/templates/simple_class.txt:
# class {class_name}:
# def __init__(self, name):
# self.name = name
#
# def greet(self):
# return f"Hello, {self.name}!"
#
# Note: The server needs to be able to find this template.
# For a packaged installation, this means the template should be in the installed package.
# For local development, ensure paths are correct relative to where server is run.
try:
templated_code = await client.code_generate(
description="Generate a simple class using a template.", # Description is still useful context
template_name="simple_class", # Name of the template file (without .txt)
parameters={"class_name": "MyGreeter"},
language="Python"
)
print("\nGenerated code from template 'simple_class':")
print(templated_code)
except Exception as e:
# This might fail if the template isn't found by the server
print(f"\nError generating code from template (ensure template exists and is accessible): {e}")
if __name__ == "__main__":
asyncio.run(main())CodexMCP includes several advanced features to enhance reliability and performance:
API responses are streamed in real-time, displaying tokens as they're generated:
- Improves user experience with immediate feedback
- Shows progress for longer generations
- Works with all tools using the OpenAI API
Identical prompts are automatically cached to improve response time and reduce API costs:
- Set
CODEXMCP_CACHE_ENABLED=0to disable caching - Configure cache timeout with
CODEXMCP_CACHE_TTL=3600(in seconds)
The system automatically handles errors with improved diagnostics:
- Error IDs are included in error messages for easier debugging
- Specific error types help diagnose issues
All tools now use a dedicated cli_backend module for Codex CLI interactions:
- Per-call CLI execution instead of long-lived pipe for improved reliability
- Automatic filesystem context awareness for all tools
- Better error handling and logging
-
"Codex executable path not configured or found"
- Ensure the Codex CLI is installed globally with
npm install -g @openai/codex - Set
CODEX_PATHenvironment variable if the binary is in a non-standard location
- Ensure the Codex CLI is installed globally with
-
API Key Issues
- Make sure your
OPENAI_API_KEYis set in the environment or.envfile - Check that the key has the correct permissions and hasn't expired
- Make sure your
-
Model Availability
- If you see "Model unavailable" errors, check that the specified model exists and is available in your OpenAI account
- You can specify a different model with the
CODEX_MODELenvironment variable
Run tests with pytest:
# Run all tests
pytest
# Run a specific test
pytest tests/test_tools.py::TestGenerateCode
# Test with coverage
pytest --cov=codexmcpMIT