Mcp Makefile Server

MCP Makefile Server

> [!TIP] > Use this MCP server to easily expose Makefile targets as MCP tools. Let AI agents execute your Makefile targets through the Model Context Protocol.

Table of Contents

• [What is the Value of mcp-makefile-server?](#what-is-the-value-of-mcp-makefile-server)
• [Features](#features)
• [TL;DR - Simplest Setup](#tldr---simplest-setup)
• [Usage Patterns](#usage-patterns)
• [Project-Scoped vs Global Configuration](#project-scoped-vs-global-configuration)
• [Quick Start](#quick-start)
• [Prerequisites](#prerequisites)
• [Installation Method 1: Using uvx (Recommended)](#installation-method-1-using-uvx-recommended)
• [Installation Method 2: Local Installation](#installation-method-2-local-installation)
• [Claude Code Setup](#claude-code-setup)
• [Advanced Configuration](#advanced-configuration)
• [Allowed Targets Filter](#allowed-targets-filter)
• [Defaults](#defaults)
• [Environment Variables](#environment-variables)
• [Output Management](#output-management)
• [Removing and Uninstalling](#removing-and-uninstalling)
• [Troubleshooting](#troubleshooting)
• [Makefile Format](#makefile-format)
• [Development](#development)
• [Best Practices](#best-practices)
• [Examples](#examples)
• [License](#license)

What is the Value of mcp-makefile-server?

| Value | What you get (benefit) | Why it matters in practice | | ---------------------------------------------- | --------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------- | | Turn your workflow into tools instantly | Anything you can run from a Makefile: scripts, CLIs, one-liners, pipelines, etc. become a first-class MCP tool | You stop “rewriting tooling” for every assistant/client and just expose what already works | | Tooling without building a tool platform | An MCP server that “just works” off your existing Make targets | You avoid bespoke MCP coding, schemas, and glue logic because your Makefile is the integration layer | | No need to remind the coding tool about the Makefile | The coding tool doesn't need to know about the Makefile, it finds out what tools it has automatically via MCP. | You can simply add new targets to the Makefile and the coding tool will automatically know about them. | | Self-service automation | Your assistant can add/adjust targets as needs evolve (you review + merge like normal code) | Tooling grows at the speed of your project | | One source of truth for “how we do things” | The Makefile becomes the canonical catalog of project actions (build, test, lint, release, migrate, etc.) | No drift between docs, tribal knowledge, CI steps, etc. | | Safer execution by design | You expose only what you want (allowlists, internal/skip markers) and keep dangerous stuff hidden | Only give the coding tool access to what it needs to do its job | | Better guidance at the point of use | ## comments become the tool’s instructions: options, inputs, side effects, outputs | The “how to use it” travels with the command, so it stays accurate as the target evolves | | Composable building blocks | Targets can depend on other targets (e.g., build: test lint) and form reliable workflows | You get a clean, modular automation graph | | Tooling portability | Makefiles work almost everywhere; you’re not locked into a specific agent ecosystem | Your automation survives client churn. New assistant? Same Make targets |

Features

| Feature | Description | |---------|-------------| | Automatic Tool Discovery | Parses Makefile and exposes documented targets as MCP tools | | Target Filtering | Use allowlists to control which targets are exposed | | Progress Notifications | MCP clients receive start/completion status updates for long-running targets | | Category Support | Organize targets with ## Category: headers | | Internal Targets | Mark targets with @internal or @skip to exclude them | | Async Execution | Non-blocking target execution with timeout support | | Output Management | Optional truncation, file output with organized subdirectories, customizable temp location | | Configurable Timeouts | Set custom timeout per target execution (default: 300s) |

TL;DR - Simplest Setup

In your project directory with a Makefile:

# Install uv (if needed)
curl -LsSf https://astral.sh/uv/install.sh | sh

# Add MCP server to your project
claude mcp add-json --scope project makefile-server '{
  "type": "stdio",
  "command": "uvx",
  "args": [
    "--from",
    "git+https://github.com/ccollicutt/mcp-makefile-server",
    "mcp-makefile-server",
    "./Makefile"
  ]
}'

# Restart Claude Code

Done! Your Makefile targets with ## comments are now available as tools.

---

Usage Patterns

Project-Scoped vs Global Configuration

Recommended: Project-Scoped

The best way to use this MCP server is to point it at your current project's Makefile using --scope project. This approach:

• Gives Claude Code access to project-specific targets
• Keeps each project's automation isolated and relevant
• Allows different projects to have different Makefile targets

Alternative: Global Configuration

You can use --scope global to make the server available across all projects. This is useful if you have:

• A shared utilities Makefile with common tasks
• Cross-project tooling that you want available everywhere

Both Configurations

You can configure both a global instance and project-specific instances:

• Global instance: Points to a shared utilities Makefile (~/makefiles/common.mk)
• Project instances: Each project points to its own ./Makefile

Each instance can point to a different Makefile and expose different targets. The global instance provides shared tools, while project instances provide project-specific automation.

---

Quick Start

Prerequisites

Install uv (if you don't have it):

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

This gives you both uv and uvx commands.

---

Installation Method 1: Using uvx (Recommended)

No cloning needed! uvx runs directly from GitHub:

# Test it works - preview your Makefile targets
uvx --from git+https://github.com/ccollicutt/mcp-makefile-server mcp-makefile-server preview ./Makefile

What this does:

• Downloads and caches the server from GitHub
• Runs the preview command on your ./Makefile
• Shows what tools would be exposed

Example output:

Found 3 targets in ./Makefile:
  • test - Run test suite
  • build - Build package
  • deploy - Deploy to production

That's it! Now skip to [Claude Code Setup](#claude-code-setup) below.

---

Installation Method 2: Local Installation

Use this if you need to modify the code.

Step 1: Clone and install

git clone https://github.com/ccollicutt/mcp-makefile-server.git
cd mcp-makefile-server
uv pip install .

Step 2: Test it works

# Preview your Makefile targets
uv run python -m mcp_makefile preview /path/to/your/Makefile

# Or just list tool names
uv run python -m mcp_makefile list /path/to/your/Makefile

---

For Development: See [DEVELOP.md](DEVELOP.md) for development setup instructions.

Claude Code Setup

Configure the MCP server for your project:

If you used Method 1 (uvx):

cd ~/projects/my-app

claude mcp add-json --scope project makefile-server '{
  "type": "stdio",
  "command": "uvx",
  "args": [
    "--from",
    "git+https://github.com/ccollicutt/mcp-makefile-server",
    "mcp-makefile-server",
    "./Makefile"
  ]
}'

If you used Method 2 (local installation):

cd ~/projects/my-app

claude mcp add-json --scope project makefile-server '{
  "type": "stdio",
  "command": "uv",
  "args": [
    "--directory",
    "/path/to/mcp-makefile-server",
    "run",
    "python",
    "-m",
    "mcp_makefile",
    "./Makefile"
  ]
}'

What this does:

• Creates .mcp.json in your project root (project-scoped)
• Configures Claude Code to use your Makefile targets as tools when working in this project

For global setup (available in all projects):

Replace --scope project with --scope global in the commands above. This creates a global MCP configuration, though project-scoped is recommended since each project typically has its own Makefile with project-specific targets.

You can configure both: A global instance for shared utilities and project-specific instances for each project's Makefile.

Next step: Restart Claude Code to load the server.

Advanced Configuration

Allowed Targets Filter

Restrict which targets can be executed:

Using uvx:

claude mcp add-json --scope project makefile-server '{
  "type": "stdio",
  "command": "uvx",
  "args": [
    "--from",
    "git+https://github.com/ccollicutt/mcp-makefile-server",
    "mcp-makefile-server",
    "./Makefile",
    "--allowed-targets",
    "test",
    "build",
    "lint"
  ]
}'

Using local installation:

claude mcp add-json --scope project makefile-server '{
  "type": "stdio",
  "command": "uv",
  "args": [
    "--directory",
    "/path/to/mcp-makefile-server",
    "run",
    "python",
    "-m",
    "mcp_makefile",
    "./Makefile",
    "--allowed-targets",
    "test",
    "build",
    "lint"
  ]
}'

Defaults

The server works out of the box with sensible defaults:

| Setting | Default Value | What it means | |---------|---------------|---------------| | Output Length | Unlimited (0) | All output is returned without truncation | | File Output | Disabled | Output is not written to files (only returned in response) | | Temp Directory | /tmp | Where temporary files are created (if file output is enabled) | | Timeout | 300 seconds | Maximum execution time per target | | Allowed Targets | All non-internal | All targets with ## comments are exposed (except @internal/@skip) | | Log Level | INFO | Standard logging verbosity |

In other words: The server returns all output directly to the client with no truncation or file writing, executes any documented target, and times out after 5 minutes.

Environment Variables

The server can also be configured via environment variables:

| Environment Variable | Description | Default | |---------------------|-------------|---------| | MCP_MAKEFILE_PATH | Path to Makefile | ./Makefile | | MCP_MAKEFILE_LOG_LEVEL | Logging level (DEBUG, INFO, WARNING, ERROR) | INFO | | MCP_MAKEFILE_ALLOWED_TARGETS | Comma-separated list of allowed targets | All non-internal targets | | MCP_MAKEFILE_MAX_OUTPUT_CHARS | Maximum characters to return from target output (0 = unlimited) | 0 (unlimited) | | MCP_MAKEFILE_WRITE_TO_FILE | Write full output to temporary files (true/false) | false | | MCP_MAKEFILE_TEMP_DIR | Base directory for temporary files | /tmp |

Using environment variables in Claude Code:

You can set environment variables in your .mcp.json configuration:

claude mcp add-json --scope project makefile-server '{
  "type": "stdio",
  "command": "uvx",
  "args": [
    "--from",
    "git+https://github.com/ccollicutt/mcp-makefile-server",
    "mcp-makefile-server",
    "./Makefile"
  ],
  "env": {
    "MCP_MAKEFILE_LOG_LEVEL": "DEBUG",
    "MCP_MAKEFILE_MAX_OUTPUT_CHARS": "5000",
    "MCP_MAKEFILE_WRITE_TO_FILE": "true",
    "MCP_MAKEFILE_TEMP_DIR": "/var/tmp"
  }
}'

This configures the server to:

• Use DEBUG logging
• Truncate output at 5000 characters
• Write full output to files in /var/tmp/mcp-makefile-{random-id}/

See Claude Code Settings Documentation for more information.

Setting environment variables in your shell:

export MCP_MAKEFILE_PATH=/path/to/Makefile
export MCP_MAKEFILE_LOG_LEVEL=DEBUG
export MCP_MAKEFILE_ALLOWED_TARGETS="test,build,lint"
export MCP_MAKEFILE_MAX_OUTPUT_CHARS=5000
export MCP_MAKEFILE_WRITE_TO_FILE=true
export MCP_MAKEFILE_TEMP_DIR=/var/tmp

Output Management

The server provides two options for managing large output:

Option 1: Truncate Output (Optional)

By default, output is unlimited. To prevent token overload, you can enable truncation:

Via environment variable:

export MCP_MAKEFILE_MAX_OUTPUT_CHARS=5000  # Set >0 to truncate, 0 = unlimited

Via command-line argument:

mcp-makefile-server serve ./Makefile --max-output-chars 5000

When output is truncated, you'll see a message like:

Note: Output exceeded 5000 characters and was truncated.
Configure targets to log verbose output to files and return summaries instead.

Option 2: Write to Temporary File

Write full output to temporary files and return the file path. The server creates a unique subdirectory for each session to organize output files.

Via environment variable:

export MCP_MAKEFILE_WRITE_TO_FILE=true

Via command-line argument:

mcp-makefile-server serve ./Makefile --write-to-file

When enabled, you'll see:

Full output written to: /tmp/mcp-makefile-4a3f2e1b/test-1234567890.log

Customize temp directory location:

# Via environment variable
export MCP_MAKEFILE_TEMP_DIR=/var/tmp

# Via command-line argument
mcp-makefile-server serve ./Makefile --write-to-file --temp-dir /var/tmp

The server automatically creates a randomized subdirectory (e.g., mcp-makefile-{random-id}) within the temp directory to organize all output files for that session.

You can combine both options to truncate the returned output while keeping a full copy in a file.

---

Removing and Uninstalling

Remove from Claude Code

To remove the MCP server from your project:

cd ~/projects/my-app
claude mcp remove "makefile-server" -s project

This removes the server from .mcp.json. Restart Claude Code to apply changes.

Uninstall the Server

If you used Method 1 (uvx):

The server is cached automatically. To clear it:

# Clear specific package from cache
uv cache clean mcp-makefile-server

# Or clear entire uv cache
uv cache clean

If you used Method 2 (local installation):

# Uninstall the package
uv pip uninstall mcp-makefile-server

# Optionally, remove the cloned directory
rm -rf /path/to/mcp-makefile-server

---

Troubleshooting

Connection Failed

If Claude Code shows "Failed to reconnect to makefile-server":

1. Check the command name is mcp-makefile-server (not mcp-makefile)
2. Verify the Makefile path is correct
3. Check the server logs: Look at Claude Code's output panel
4. Test the server manually:

``bash uvx --from git+https://github.com/ccollicutt/mcp-makefile-server mcp-makefile-server preview ./Makefile ``

---

Makefile Format

Your Makefile must use the standard self-documenting format with ## comments:

.PHONY: test build deploy

## Category: Testing
test: ## Run test suite with pytest (outputs results to stdout)
	pytest

lint: ## Check code style and formatting with ruff (reports issues found)
	ruff check .

## Category: Building
build: test ## Build Python package distribution (runs tests first, creates dist/ directory with wheel and sdist)
	python -m build

# Mark targets as internal (NOT exposed)
deploy-prod: ## @internal Deploy to production
	./deploy.sh --prod

# Regular targets ARE exposed
deploy-stagi

…

## Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [ccollicutt](https://github.com/ccollicutt)
- **Source:** [ccollicutt/mcp-makefile-server](https://github.com/ccollicutt/mcp-makefile-server)
- **License:** MIT

Install and usage instructions live in the source repository linked above.