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