Which integrations are available for this server?

Provides tools for reading and analyzing Symfony projects, including project metadata, routes, Twig templates, services, and PHP source code, enabling AI models to understand and work with Symfony applications.

How do I use symfony-php-mcp?

1. Click on "Install Server". 2. Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state. 3. In the chat, type @ followed by the MCP server name and your instructions, e.g., "@symfony-php-mcp List all Symfony routes" That's it! The server will respond to your query, and you can continue using it as needed. Here is a step-by-step guide with screenshots.

symfony-php-mcp

by maschmann

Overview Schema Related Servers Score Discussions

Python

Local

symfony-php-mcp

A production-ready Model Context Protocol (MCP) server that bridges your Symfony/PHP project with LLMs such as Claude. It exposes tools that let the AI read your project's routes, services, Twig templates, and PHP source code — without ever needing direct filesystem access from the LLM itself.

Claude Desktop / Claude Code
        │
        │  MCP (stdio)
        ▼
symfony-php-mcp  ──► reads ──► composer.json, symfony.lock, services.yaml, *.twig
                 ──► runs  ──► php bin/console debug:router / debug:container

Related MCP server: @lex-tools/codebase-context-dumper

Features

Tool	What it does	PHP needed?
`get_project_overview`	Reads `composer.json` + `symfony.lock` – PHP version, Symfony version, all packages	No
`find_route`	Runs `debug:router --format=json`, filters by URL pattern and HTTP method	Yes
`analyze_twig`	Finds a `.twig` file and extracts `extends`, `include`, `block`, macros	No
`list_services`	Reads `config/services.yaml` or runs `debug:container --format=json`	Optional
`read_code_context`	Reads a PHP file, strips doc-block comments to save tokens	No

Quick Start

# Requires uv — https://docs.astral.sh/uv/
SYMFONY_PROJECT_ROOT=/path/to/your/symfony/app uvx symfony-php-mcp

The server speaks MCP over stdio and is designed to be launched by your MCP client (Claude Desktop, Claude Code, etc.), not run manually.

Installation

Via uvx (recommended)

uvx runs the package from the PyPI / GitHub registry with no permanent install:

// claude_desktop_config.json
{
  "mcpServers": {
    "symfony": {
      "command": "uvx",
      "args": ["symfony-php-mcp"],
      "env": {
        "SYMFONY_PROJECT_ROOT": "/path/to/your/symfony-app"
      }
    }
  }
}

Install from GitHub (before it's on PyPI):

{
  "mcpServers": {
    "symfony": {
      "command": "uvx",
      "args": ["--from", "git+https://github.com/maschmann/symfony-php-mcp", "symfony-mcp"],
      "env": {
        "SYMFONY_PROJECT_ROOT": "/path/to/your/symfony-app"
      }
    }
  }
}

Via local clone

git clone https://github.com/maschmann/symfony-php-mcp
cd symfony-php-mcp
uv sync

{
  "mcpServers": {
    "symfony": {
      "command": "uv",
      "args": ["run", "--project", "/path/to/symfony-php-mcp", "symfony-mcp"],
      "env": {
        "SYMFONY_PROJECT_ROOT": "/path/to/your/symfony-app"
      }
    }
  }
}

Configuration

Configuration is resolved in priority order: environment variables → .symfony-mcp.json → built-in defaults.

Environment Variables

Set these in your MCP client's env block.

Variable	Default	Description
`SYMFONY_PROJECT_ROOT`	current working directory	Required. Absolute path to your Symfony project (the directory containing `composer.json`).
`PHP_EXECUTABLE`	`php`	PHP binary or wrapper command. Use `ddev php`, `lando php`, or a full path like `/usr/bin/php8.3`.
`DOCKER_CONTAINER`	(none)	Docker container name. When set, commands run as `docker exec <container> php …`. Takes precedence over `PHP_EXECUTABLE`.
`DOCKER_EXEC_USER`	(none)	Optional `-u <user>` for `docker exec`. Useful when the container runs PHP as `www-data`.
`CONSOLE_PATH`	`bin/console`	Path to `bin/console` relative to `SYMFONY_PROJECT_ROOT`. Rarely needs changing.
`COMMAND_TIMEOUT`	`30`	Seconds before a PHP subprocess is killed. Increase for large projects or slow containers.

Project-local config file (`.symfony-mcp.json`)

Place this file in your Symfony project root to commit PHP runtime preferences alongside the project code. Great for teams using DDEV or Docker Compose.

{
  "php_executable": "php",
  "docker_container": null,
  "docker_exec_user": null,
  "console_path": "bin/console",
  "command_timeout": 30
}

Example for a DDEV project:

{
  "php_executable": "ddev php",
  "command_timeout": 60
}

Example for a Docker Compose project:

{
  "docker_container": "my-project-php-1",
  "docker_exec_user": "www-data",
  "command_timeout": 45
}

Configuration priority

Environment variables (MCP client env block)
        ↓  (override)
.symfony-mcp.json  (in SYMFONY_PROJECT_ROOT)
        ↓  (override)
Built-in defaults

Environment variables always win. This means you can commit a .symfony-mcp.json with sensible defaults for your team while still being able to override them per-machine via env vars.

Claude Desktop Setup

The claude_desktop_config.json file lives at:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
Windows: %APPDATA%\Claude\claude_desktop_config.json
Linux: ~/.config/Claude/claude_desktop_config.json

Local PHP

{
  "mcpServers": {
    "symfony": {
      "command": "uvx",
      "args": ["symfony-php-mcp"],
      "env": {
        "SYMFONY_PROJECT_ROOT": "/home/alice/projects/my-symfony-app"
      }
    }
  }
}

Docker

Works with any Docker Compose project. The container must be running when Claude Desktop starts (or before you use the tools).

{
  "mcpServers": {
    "symfony": {
      "command": "uvx",
      "args": ["symfony-php-mcp"],
      "env": {
        "SYMFONY_PROJECT_ROOT": "/home/alice/projects/my-symfony-app",
        "DOCKER_CONTAINER": "my-symfony-app-php-1",
        "DOCKER_EXEC_USER": "www-data"
      }
    }
  }
}

Finding your container name: run docker ps and look at the NAMES column.

DDEV

{
  "mcpServers": {
    "symfony": {
      "command": "uvx",
      "args": ["symfony-php-mcp"],
      "env": {
        "SYMFONY_PROJECT_ROOT": "/home/alice/projects/my-symfony-app",
        "PHP_EXECUTABLE": "ddev php"
      }
    }
  }
}

Alternatively, commit a .symfony-mcp.json to your project:

{
  "php_executable": "ddev php"
}

Then the MCP config only needs SYMFONY_PROJECT_ROOT.

Lando

{
  "mcpServers": {
    "symfony": {
      "command": "uvx",
      "args": ["symfony-php-mcp"],
      "env": {
        "SYMFONY_PROJECT_ROOT": "/home/alice/projects/my-symfony-app",
        "PHP_EXECUTABLE": "lando php"
      }
    }
  }
}

Sail

Laravel Sail is a thin Docker wrapper but the pattern works for Symfony projects using a similar setup:

{
  "env": {
    "SYMFONY_PROJECT_ROOT": "/home/alice/projects/my-project",
    "DOCKER_CONTAINER": "my-project-laravel.test-1"
  }
}

Tools Reference

`get_project_overview`

Returns a Markdown summary of the project. Call this first to give the LLM context before using other tools.

Parameters: none

Returns:

# Symfony Project: `acme/store`
> An e-commerce platform built with Symfony

## Runtime
| Key | Value |
|-----|-------|
| PHP requirement | `>=8.2` |
| Symfony version | `7.1.3` |
| APP_ENV | `dev` |

## Installed Packages
### Symfony Components
| Package | Version | Dev? |
...

`find_route`

Finds routes matching a URL pattern or route name.

Parameters:

Parameter	Type	Required	Description
`url_pattern`	string	Yes	Substring or regex to match against route paths and names. E.g. `/api/user`, `user_show`, `^/admin`
`method`	string	No	HTTP method filter: `GET`, `POST`, `PUT`, `PATCH`, `DELETE`. Empty = any.

Example:

Tool: find_route
url_pattern: /api/user
method: GET

Found **3** route(s) matching `/api/user`

| Route Name | Path | Methods | Controller |
|------------|------|---------|------------|
| `api_user_list` | `/api/users` | `GET` | `UserController::list` |
| `api_user_show` | `/api/users/{id}` | `GET` | `UserController::show` |
| `api_user_me`   | `/api/user/me`    | `GET` | `UserController::me`   |

Requires: PHP + bin/console

`analyze_twig`

Analyses a Twig template without running PHP.

Parameters:

Parameter	Type	Required	Description
`template_name`	string	Yes	Template name as used in Twig, or a partial name. E.g. `user/show.html.twig`, `show`, `user/`

Example:

Tool: analyze_twig
template_name: user/show.html.twig

## Template: `templates/user/show.html.twig`

### Inheritance
Extends: `base.html.twig`

### Included / Embedded Templates
| Type | Template |
|------|----------|
| include | `_partials/user_card.html.twig` |
| include | `_partials/breadcrumb.html.twig` |

### Defined Blocks
`title`, `content`, `scripts`

### Template Variables
`user`, `posts`, `pagination`

`list_services`

Lists service definitions from config/services.yaml or the compiled container.

Parameters:

Parameter	Type	Default	Description
`filter_pattern`	string	`""`	Regex/substring to filter by service ID or class. E.g. `App\\Service`, `mailer`, `doctrine`
`use_container_debug`	bool	`false`	Use `debug:container --format=json` instead of YAML. Required to see auto-wired / framework services.

Example – find all mailer services:

Tool: list_services
filter_pattern: mailer
use_container_debug: true

`read_code_context`

Reads a PHP file with optional comment stripping to reduce token usage.

Parameters:

Parameter	Type	Default	Description
`file_path`	string	—	Path relative to project root. E.g. `src/Controller/UserController.php`
`strip_doc_comments`	bool	`true`	Strip `/** … /` and `/ … */` blocks. Saves ~20-40% tokens on typical controllers.
`strip_line_comments`	bool	`false`	Also strip `//` comments. Use when you need maximum token efficiency.

Example:

Tool: read_code_context
file_path: src/Controller/UserController.php

## `src/Controller/UserController.php`

| Property | Value |
|----------|-------|
| Original  | 187 lines / 6,842 chars |
| After processing | 134 lines / 4,201 chars |
| Token savings | ~39% (block comments stripped) |

```php
  1 | <?php
  2 |
  3 | namespace App\Controller;
...

Docker / Container Environments (in depth)

How command routing works

When DOCKER_CONTAINER is set, every PHP/console invocation becomes:

docker exec [-u <DOCKER_EXEC_USER>] <DOCKER_CONTAINER> php bin/console <args>

When PHP_EXECUTABLE is set to ddev php:

ddev php bin/console <args>

The server never modifies the project files inside the container.

Docker Compose tips

Container name – use docker ps to find the exact name. For docker compose, it's usually <project>-<service>-1.
File paths – SYMFONY_PROJECT_ROOT should point to the host path since the server reads files directly via the Python filesystem layer. Only debug:router / debug:container commands run inside the container.
Working directory – commands are run in SYMFONY_PROJECT_ROOT on the host. If your container mounts the project at a different path, set CONSOLE_PATH accordingly — or ensure bin/console is accessible from the host path.
Container not running – the server will return a helpful error. Start your containers first: docker compose up -d.

DDEV tips

# List DDEV projects
ddev list

# Ensure the project is running
ddev start

# Test PHP is accessible
ddev php --version

.symfony-mcp.json for DDEV:

{
  "php_executable": "ddev php",
  "command_timeout": 60
}

Lando tips

# Ensure the project is running
lando start

# Test PHP is accessible
lando php --version

.symfony-mcp.json for Lando:

{
  "php_executable": "lando php"
}

Development

# Clone
git clone https://github.com/maschmann/symfony-php-mcp
cd symfony-php-mcp

# Install dependencies (requires uv — https://docs.astral.sh/uv/)
uv sync

# Run the server (will block waiting for MCP stdio input)
uv run symfony-php-mcp

# Run tests
uv run pytest

# Lint
uv run ruff check src/
uv run ruff format --check src/

Project structure

src/symfony_mcp/
├── server.py        # FastMCP server, lifespan, tool decorators, main()
├── config.py        # ServerConfig: env vars + .symfony-mcp.json merge logic
├── executor.py      # PhpExecutor: subprocess wrapper with Docker/wrapper support
├── indexer.py       # SymbolIndex: PHP regex scanner + JSON persistence
└── tools/
    ├── project.py   # get_project_overview
    ├── router.py    # find_route
    ├── twig.py      # analyze_twig
    ├── services.py  # list_services
    ├── code.py      # read_code_context
    └── index.py     # build_index, find_symbol, search_code

Symbol index

The index is stored at <symfony-project>/.symfony-mcp-index.json. Add it to the project's .gitignore:

# symfony-php-mcp symbol index
.symfony-mcp-index.json

Typical workflow:

1. build_index                      — first time, or after major refactors
2. find_symbol "UserController"     — get file + line number instantly
3. read_code_context src/...php     — read the implementation

The index updates incrementally (only changed files are re-scanned), so calling build_index after saving a few files is fast.

Adding a new tool

Create src/symfony_mcp/tools/my_tool.py with a plain function.
Register it in server.py with @mcp.tool().
Add a docstring – FastMCP uses it as the tool description.

Troubleshooting

"Binary not found: 'php'"

PHP is not in the PATH used by the MCP server process.

Fix options:

Install PHP: apt install php-cli / brew install php
Use a full path: PHP_EXECUTABLE=/usr/bin/php8.3
Use Docker: DOCKER_CONTAINER=my-php-container
Use DDEV: PHP_EXECUTABLE=ddev php

"Symfony console not found"

SYMFONY_PROJECT_ROOT is pointing to the wrong directory, or bin/console is missing.

Fix: Make sure SYMFONY_PROJECT_ROOT is the directory that contains both composer.json and bin/console.

ls /your/project/bin/console   # should exist

"Command timed out"

The PHP command took longer than COMMAND_TIMEOUT seconds.

Fix: Increase the timeout:

// .symfony-mcp.json
{ "command_timeout": 120 }

Or set COMMAND_TIMEOUT=120 in the MCP env block.

"Cannot inspect container"

The Docker container is not running.

Fix:

docker compose up -d           # Docker Compose
ddev start                     # DDEV
lando start                    # Lando

Claude Desktop doesn't see the server

Restart Claude Desktop after editing claude_desktop_config.json.
Check the MCP server logs in Claude Desktop → Settings → Developer → MCP Servers.
Run the server manually to check for errors:
```
SYMFONY_PROJECT_ROOT=/path/to/project uvx symfony-php-mcp
```
It should start silently (waiting for stdio input). Any error on startup will print to stderr.

"Error parsing config/services.yaml"

Your services.yaml has a syntax error or uses YAML features not supported by PyYAML.

Fix: Use use_container_debug=true in list_services as a fallback:

Tool: list_services
filter_pattern: App\
use_container_debug: true

License

MIT — see LICENSE.

Install Server

license - permissive license

quality - not tested

maintenance

How are these scores calculated?

Maintenance

–Maintainers

–Response time

0dRelease cycle

3Releases (12mo)

Commit activity

Resources

GitHub Repository

Need Help?

Related Servers

Unclaimed servers have limited discoverability.

Looking for Admin?

If you are the server author, to access and configure the admin panel.

Tools

Latest Blog Posts

Lightport: Open-Sourcing Glama's AI Gateway
By punkpeye on April 27, 2026.
open source
OpenAI
Tool Definition Quality Score (TDQS)
By punkpeye on April 3, 2026.
mcp
The Hackers Who Tracked My Sleep Cycle
By punkpeye on March 26, 2026.
security

MCP directory API

We provide all the information about MCP servers via our MCP API.

curl -X GET 'https://glama.ai/api/mcp/v1/servers/maschmann/symfony-php-mcp'

If you have feedback or need assistance with the MCP directory API, please join our Discord server

symfony-php-mcp

Table of Contents

Features

Quick Start

Installation

Via uvx (recommended)

Via local clone

Configuration

Environment Variables

Project-local config file (.symfony-mcp.json)

Configuration priority

Claude Desktop Setup

Local PHP

Docker

DDEV

Lando

Sail

Tools Reference

get_project_overview

find_route

analyze_twig

list_services

read_code_context

Docker / Container Environments (in depth)

How command routing works

Docker Compose tips

DDEV tips

Lando tips

Development

Project structure

Symbol index

Adding a new tool

Troubleshooting

"Binary not found: 'php'"

"Symfony console not found"

"Command timed out"

"Cannot inspect container"

Claude Desktop doesn't see the server

"Error parsing config/services.yaml"

License

Maintenance

Resources

Looking for Admin?

Tools

Latest Blog Posts

MCP directory API

Project-local config file (`.symfony-mcp.json`)

`get_project_overview`

`find_route`

`analyze_twig`

`list_services`

`read_code_context`