Skip to main content
Glama

Evidence MCP Server

An MCP (Model Context Protocol) server that provides tools for AI assistants to help users create Evidence reports and dashboards.

Installation

# Clone and install
git clone https://github.com/jaho5/evidence-mcp.git
cd evidence-mcp
uv sync

Related MCP server: database-explorer-mcp

Usage

# Run the MCP server
uv run evidence-mcp

# With custom Evidence project path
EVIDENCE_MCP_EVIDENCE_PROJECT_PATH=/path/to/project uv run evidence-mcp

Configuration

Environment variables:

Variable

Default

Description

EVIDENCE_MCP_EVIDENCE_DEV_URL

http://localhost:3000

Evidence dev server URL

EVIDENCE_MCP_EVIDENCE_PROJECT_PATH

-

Path to Evidence project

EVIDENCE_MCP_TRANSPORT

stdio

Transport mode: stdio, sse

Tools

get_metadata

Returns database schema from Evidence's DuckDB connection.

read_docs

Retrieves Evidence documentation using hierarchical lookup.

edit_page

Proposes changes to the current Evidence markdown page.

debug_code

Analyzes validation errors and suggests fixes.


Claude Code Setup

Add to your Claude Code MCP settings (~/.claude.json):

{
  "mcpServers": {
    "evidence-mcp": {
      "command": "uv",
      "args": ["run", "--directory", "/path/to/evidence-mcp", "evidence-mcp"],
      "env": {
        "EVIDENCE_MCP_EVIDENCE_PROJECT_PATH": "/path/to/your/evidence/project"
      }
    }
  }
}

Or add via CLI:

claude mcp add evidence-mcp -- uv run --directory /path/to/evidence-mcp evidence-mcp

To verify installation:

claude mcp list

Claude Desktop Setup

Add to Claude Desktop config (~/Library/Application Support/Claude/claude_desktop_config.json on macOS or %APPDATA%\Claude\claude_desktop_config.json on Windows):

{
  "mcpServers": {
    "evidence-mcp": {
      "command": "uv",
      "args": ["run", "--directory", "/path/to/evidence-mcp", "evidence-mcp"],
      "env": {
        "EVIDENCE_MCP_EVIDENCE_PROJECT_PATH": "/path/to/your/evidence/project"
      }
    }
  }
}

Programmatic Usage (MCP Client)

import asyncio
from mcp import ClientSession, StdioServerParameters
from mcp.client.stdio import stdio_client

async def main():
    server_params = StdioServerParameters(
        command="uv",
        args=["run", "--directory", "/path/to/evidence-mcp", "evidence-mcp"],
        env={
            "EVIDENCE_MCP_EVIDENCE_PROJECT_PATH": "/path/to/your/evidence/project"
        }
    )

    async with stdio_client(server_params) as (read, write):
        async with ClientSession(read, write) as session:
            # Initialize the connection
            await session.initialize()

            # List available tools
            tools = await session.list_tools()
            print("Available tools:", [t.name for t in tools.tools])

            # Call get_metadata
            result = await session.call_tool("get_metadata", arguments={})
            print("Metadata:", result.content)

            # Call read_docs
            result = await session.call_tool("read_docs", arguments={
                "doc_type": "charts",
                "component": "LineChart"
            })
            print("Docs:", result.content)

asyncio.run(main())

With OpenAI Agents SDK

First, run the server in SSE mode:

EVIDENCE_MCP_TRANSPORT=sse \
EVIDENCE_MCP_EVIDENCE_PROJECT_PATH=/path/to/your/evidence/project \
uv run evidence-mcp

Then use HostedMCPTool to connect:

from agents import Agent, HostedMCPTool

agent = Agent(
    name="Evidence Assistant",
    instructions="Help users create Evidence reports and dashboards.",
    tools=[
        HostedMCPTool(
            tool_config={
                "type": "mcp",
                "server_label": "evidence",
                "server_url": "http://localhost:8000/sse",
                "require_approval": "never",
            }
        )
    ],
)

Development

# Install with dev dependencies
uv sync --extra dev

# Run tests
uv run pytest

# Run tests with coverage
uv run pytest --cov=evidence_mcp

# Lint
uv run ruff check

# Format
uv run ruff format

Available Tools

4 tools
debug_codeC

Analyzes validation errors and suggests fixes.

Examines the provided errors and page content to identify issues and generate actionable fix suggestions.

Returns: Dictionary with 'analysis', 'suggestions' list, and optionally 'fixed_content'

Inputs: errors (required), page_content (required).

edit_pageC

Proposes changes to the current Evidence markdown page.

Validates the proposed content for common Evidence syntax issues and returns the content with any warnings detected.

Returns: Dictionary with 'success', 'description', 'content', and 'warnings' list

Inputs: edit (required), description (required).

get_metadataA

Returns database schema from Evidence's DuckDB connection.

Returns a JSON object with tables and their columns, including data types. Use this to understand what data is available for queries.

Returns: Dictionary with 'tables' array, each containing 'name' and 'columns'

Inputs: no named parameters.

read_docsB

Retrieves Evidence documentation using hierarchical lookup.

Categories:

  • charts: LineChart, BarChart, AreaChart, Heatmap, SankeyDiagram, etc.

  • data: Value, BigValue, DataTable, Delta

  • inputs: Dropdown, Slider, DateInput, ButtonGroup, etc.

  • ui: Grid, Tabs, Modal, Alert, Accordion, etc.

  • maps: USMap, AreaMap, PointMap, BubbleMap, BaseMap

  • custom: CustomComponent, ComponentQueries

  • core-concepts: queries, syntax, loops, formatting, filters, etc.

  • data-sources: postgres, mysql, snowflake, bigquery, duckdb, etc.

  • deployment: vercel, netlify, cloudflare-pages, etc.

  • guides: best-practices, troubleshooting, chart-cheat-sheet

  • reference: cli, markdown, layouts

  • plugins: source-plugins, component-plugins

  • getting-started: install-evidence, build-your-first-app

Returns: Dictionary with 'title', 'content', and 'related_docs' for further exploration

Inputs: doc_type (required), component.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    B3.2/5.0

    Scored across 4 tools

    Disambiguation4/5

    Tools are mostly distinct: debug_code analyzes errors, edit_page modifies content, get_metadata queries schema, read_docs fetches documentation. Minor overlap between debug_code and edit_page as both involve page content, but their purposes are clear.

    Naming Consistency5/5

    All tool names follow a consistent verb_noun pattern in lowercase with underscores: debug_code, edit_page, get_metadata, read_docs. No deviation.

    Tool Count5/5

    Four tools is well-scoped for an Evidence MCP server, covering core needs like debugging, editing, schema discovery, and documentation. Not too few or too many.

    Completeness2/5

    Significant gaps: missing tools for creating, listing, or deleting pages, and no tool to run queries or fetch actual data from the database. The surface covers only partial workflows, likely causing agent failures in common tasks.

    Maintenance

    ActivityInactive
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • F
      license
      B
      quality
      D
      maintenance
      Enables AI assistants to interact with GitHub repositories, Confluence documentation, and Databricks Unity Catalog through comprehensive tools for code exploration, documentation retrieval, and data schema management.
      19
      -
    • A
      license
      A
      quality
      D
      maintenance
      Enables AI assistants to connect to and interact with PostgreSQL, MySQL, SQLite, and MongoDB databases through natural language, supporting schema exploration, query execution, data export, and more.
      13
      MIT