<h1 align="center" style="border-bottom: none">
    <div>
        <a href="https://phoenix.arize.com/?utm_medium=github&utm_content=header_img&utm_campaign=phoenix-mcp">
            <picture>
                <source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/Arize-ai/phoenix-assets/refs/heads/main/logos/Phoenix/phoenix.svg">
                <source media="(prefers-color-scheme: light)" srcset="https://raw.githubusercontent.com/Arize-ai/phoenix-assets/refs/heads/main/logos/Phoenix/phoenix-white.svg">
                <img alt="Arize Phoenix logo" src="https://raw.githubusercontent.com/Arize-ai/phoenix-assets/refs/heads/main/logos/Phoenix/phoenix.svg" width="100" />
            </picture>
        </a>
        <br>
        Arize Phoenix MCP Server
    </div>
</h1>

<p align="center">
    <a href="https://www.npmjs.com/package/@arizeai/phoenix-mcp">
        <img src="https://img.shields.io/npm/v/%40arizeai%2Fphoenix-mcp" alt="NPM Version">
    </a>
    <a href="https://github.com/Arize-ai/phoenix/blob/main/js/packages/phoenix-mcp/LICENSE">
        <img src="https://img.shields.io/badge/License-Apache_2.0-blue.svg" alt="License">
    </a>
    <img src="https://badge.mcpx.dev?status=on" title="MCP Enabled"/>
    <a href="https://cursor.com/install-mcp?name=phoenix&config=eyJjb21tYW5kIjoibnB4IC15IEBhcml6ZWFpL3Bob2VuaXgtbWNwQGxhdGVzdCAtLWJhc2VVcmwgaHR0cDovL2xvY2FsaG9zdDo2MDA2IC0tYXBpS2V5IHlvdXItYXBpLWtleSJ9">
        <img src="https://cursor.com/deeplink/mcp-install-dark.svg" alt="Add Arize Phoenix MCP server to Cursor" height=20 />
    </a>
    <img referrerpolicy="no-referrer-when-downgrade" src="https://static.scarf.sh/a.png?x-pxid=8e8e8b34-7900-43fa-a38f-1f070bd48c64&page=js/packages/phoenix-mcp/README.md" />
</p>

Phoenix MCP Server is an implementation of the Model Context Protocol for the Arize Phoenix platform. It provides a unified interface to Phoenix's capabilities.

You can use Phoenix MCP Server for:

- **Projects Management**: List and explore projects that organize your observability data
- **Traces, Spans & Annotations**: Retrieve traces, spans, and annotation configs for analysis and debugging
- **Sessions**: Explore conversation flows and session-level annotations
- **Prompts Management**: Create, list, update, and iterate on prompts
- **Datasets**: Explore datasets and synthesize new examples
- **Experiments**: Pull experiment results and visualize them with the help of an LLM

Don't see a use-case covered? `@arizeai/phoenix-mcp` is [open-source](https://github.com/Arize-ai/phoenix)! Issues and PRs welcome.

## Installation

This MCP server can be used with `npx` and can be directly integrated with clients like Claude Desktop, Cursor, and more.

```json
{
  "mcpServers": {
    "phoenix": {
      "command": "npx",
      "args": [
        "-y",
        "@arizeai/phoenix-mcp@latest",
        "--baseUrl",
        "https://my-phoenix.com",
        "--apiKey",
        "your-api-key"
      ]
    }
  }
}
```

## Development

## Install

This package is managed via a pnpm workspace.

```sh
// From the /js/ directory
pnpm install
pnpm build
```

This only needs to be repeated if dependencies change or there is a change to the phoenix-client.

### Building

To build the project:

```sh
pnpm build
```

### Development Mode

To run in development mode:

```bash
pnpm dev
```

### Debugging

You can build and run the MCP inspector using the following:

```bash
pnpm inspect
```

## Environment Variables

When developing, the server requires the following environment variables:

- `PHOENIX_API_KEY`: Your Phoenix API key
- `PHOENIX_ENDPOINT`: The base URL for Phoenix
- `PHOENIX_PROJECT`: Optional default project for project-scoped tools (alias: `PHOENIX_PROJECT_NAME`)
- `PHOENIX_CLIENT_HEADERS`: Optional JSON-encoded request headers

Make sure to set these in a `.env` file. See `.env.example`.

At runtime the server also discovers the nearest `.env.phoenix` file at or
above the working directory. Process environment variables and command-line
options take precedence. If a higher-priority API key is paired with an
endpoint from the file, the server warns once and continues. Set
`PHOENIX_DISCOVER_CONFIG=false` to disable discovery.

## Tool Coverage

The MCP server covers the main operational Phoenix workflows:

**Prompts** — `list-prompts`, `get-prompt`, `get-latest-prompt`, `get-prompt-by-identifier`, `get-prompt-version`, `list-prompt-versions`, `get-prompt-version-by-tag`, `list-prompt-version-tags`, `add-prompt-version-tag`, `upsert-prompt`

**Projects** — `list-projects`, `get-project`

**Traces** — `list-traces`, `get-trace`

**Spans** — `get-spans`, `get-span-annotations`

**Sessions** — `list-sessions`, `get-session`

**Annotation Configs** — `list-annotation-configs`

**Datasets** — `list-datasets`, `get-dataset`, `get-dataset-examples`, `get-dataset-experiments`, `add-dataset-examples`

**Experiments** — `list-experiments-for-dataset`, `get-experiment-by-id`

For Phoenix documentation search, use the separate Phoenix Docs MCP server instead of this package.

## Community

Join our community to connect with thousands of AI builders:

- 🌍 Join our [Slack community](https://join.slack.com/t/arize-ai/shared_invite/zt-3r07iavnk-ammtATWSlF0pSrd1DsMW7g).
- 📚 Read the [Phoenix documentation](https://arize.com/docs/phoenix).
- 💡 Ask questions and provide feedback in the _#phoenix-support_ channel.
- 🌟 Leave a star on our [GitHub](https://github.com/Arize-ai/phoenix).
- 🐞 Report bugs with [GitHub Issues](https://github.com/Arize-ai/phoenix/issues).
- 𝕏 Follow us on [𝕏](https://twitter.com/ArizePhoenix).
- 💼 Follow us on [LinkedIn](https://www.linkedin.com/showcase/113218220).
- 🗺️ Check out our [roadmap](https://github.com/orgs/Arize-ai/projects/45) to see where we're heading next.

## License

Apache 2.0