evidence-mcp
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@evidence-mcp show me the database schema"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
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 syncRelated 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-mcpConfiguration
Environment variables:
Variable | Default | Description |
|
| Evidence dev server URL |
| - | Path to Evidence project |
|
| 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-mcpTo verify installation:
claude mcp listClaude 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-mcpThen 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 formatAvailable Tools
4 toolsdebug_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
Scored across 4 tools
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.
All tool names follow a consistent verb_noun pattern in lowercase with underscores: debug_code, edit_page, get_metadata, read_docs. No deviation.
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.
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
Related MCP Connectors
The all-in-one data stack for agents. Upload files, run SQL, evolve tables, and render charts.
Work with your database from AI tools: ask, export, approved changes, and scheduled jobs.
Query your team's drift, vulnerability, and upgrade data from any AI assistant. OAuth 2.1, 51 tools.
PDF, image, video, OCR, screenshot, SQL, QR and text tools for agents. No API key, no signup.
Related MCP Servers
- FlicenseBqualityDmaintenanceEnables 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-
- AlicenseAqualityDmaintenanceEnables 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.13MIT
- FlicenseNot gradedqualityAmaintenanceEnables AI assistants to execute SQL, explore database schemas and sample data, inspect system metrics, and generate Plotly charts from query results.-
- FlicenseNot gradedqualityAmaintenanceEnables AI assistants to execute SQL, explore schemas, retrieve internal metrics, generate Plotly charts, and obtain table/database overviews from a connected data warehouse.-