# langfuse-mcp

MCP server for [Langfuse](https://langfuse.com) — lets Claude Code create projects, manage API keys, and query traces without touching the web UI.

Designed to work with **[langfuse-kickstart](https://github.com/dominic-righthere/langfuse-kickstart)**, a self-hosted Langfuse v3 stack running locally via Docker Compose.

---

## Tools

| Tool | Description |
|------|-------------|
| `list_projects` | List all projects accessible with the current API key |
| `list_organizations` | List all organizations |
| `create_project` | Create a new project inside an organization |
| `create_api_key` | Create a new pk/sk pair for a project |
| `list_api_keys` | List API keys for a project |
| `delete_api_key` | Delete an API key by ID |
| `list_traces` | List traces with optional filters |
| `get_trace` | Get full trace details including observations |
| `list_sessions` | List sessions |
| `list_scores` | List scores with optional filters |
| `create_score` | Create a score on a trace or observation |
| `list_observations` | List spans, generations, and events |
| `list_datasets` | List datasets |
| `get_dataset` | Get a dataset and its items |
| `list_prompts` | List prompts in the prompt library |
| `get_prompt` | Get a prompt by name, version, or label |

---

## Requirements

- Python 3.11+
- [uv](https://docs.astral.sh/uv/)
- A running Langfuse instance (see [langfuse-kickstart](https://github.com/dominic-righthere/langfuse-kickstart))

---

## Setup

```bash
git clone https://github.com/dominic-righthere/langfuse-mcp
cd langfuse-mcp
cp .env.example .env
```

Edit `.env`:

```env
LANGFUSE_HOST=http://langfuse.localhost
LANGFUSE_PUBLIC_KEY=pk-lf-kickstart
LANGFUSE_SECRET_KEY=sk-lf-kickstart
LANGFUSE_DATABASE_URL=postgresql://langfuse:YOUR_POSTGRES_PASSWORD@localhost:5432/langfuse
```

`LANGFUSE_DATABASE_URL` is needed for admin tools (`create_project`, `create_api_key`, etc.) that write directly to Postgres. With langfuse-kickstart, Postgres is exposed on `127.0.0.1:5432` — use the `POSTGRES_PASSWORD` from your kickstart `.env`.

---

## Claude Code integration

Add to your `.mcp.json` (project-level) or `claude_desktop_config.json`:

```json
{
  "mcpServers": {
    "langfuse": {
      "command": "uv",
      "args": ["run", "--project", "/path/to/langfuse-mcp", "langfuse-mcp"],
      "env": {
        "LANGFUSE_HOST": "http://langfuse.localhost",
        "LANGFUSE_PUBLIC_KEY": "pk-lf-kickstart",
        "LANGFUSE_SECRET_KEY": "sk-lf-kickstart",
        "LANGFUSE_DATABASE_URL": "postgresql://langfuse:YOUR_POSTGRES_PASSWORD@localhost:5432/langfuse"
      }
    }
  }
}
```

Replace `/path/to/langfuse-mcp` with the actual path to the cloned repo.

Alternatively, if you use a `.env` file in the repo root, you can omit the `env` block and let the server load it automatically.

---

## Notes

- `create_api_key` returns the secret key only at creation time — store it immediately.
- Admin tools (`create_project`, `create_api_key`, `delete_api_key`, `list_organizations`) connect directly to Postgres. If Langfuse changes its schema in a major version these tools may need updating.
- The REST API tools (`list_traces`, `get_trace`, etc.) use the public Langfuse API and are schema-stable.

---

## License

MIT