langfuse-mcp

langfuse-mcp

MCP server for Langfuse — lets Claude Code create projects, manage API keys, and query traces without touching the web UI.

Designed to work with 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
• A running Langfuse instance (see langfuse-kickstart)

---

Setup

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

Edit .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:

{
  "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