harpd-mcp
OfficialThis server lets AI agents query Harpd's open datasets over MCP stdio, with provenance on every result.
Search & browse the product catalog:
search_products(free-text/category/verification search),get_product(lookup by id, slug, or name), andget_products(paginated listing with filters on category, product type, verification, and rankPoints range).Read Rank boards:
get_rankingsreturns the overall/monthly/weekly boards with period metadata;get_category_rankingreads one of the 28 category boards;get_ranking_historycompares the three live snapshots side by side (and explicitly states there is no multi-month time series).Query Discovery Index coverage slices:
get_ai_agents(334 records),get_ai_tools(693), andget_developer_tools(1,918) return coverage lists with domains, descriptions, discovery sources, and observed_at timestamps — not rankings.Read research output:
get_researchreturns monthly research reports and the AI Market Index (27 category rows with product counts and rank-point share).Verify claims:
get_evidencequeries the Evidence Graph to check whether statements about Harpd data are supported, including claims Harpd explicitly does not make.Get sourced, citable answers: every response includes provenance (source, sourceUrl, dataset path, updatedAt, license, attribution, evidence) and disclaimers, so agents can quote where data came from and avoid treating rankPoints as quality.
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., "@harpd-mcp Show me the AI Market Index data with provenance"
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.
harpd-mcp
Query Harpd's public AI product, ranking, research and evidence datasets directly from AI agents.
harpd-mcp is a Model Context Protocol server.
It gives an AI agent 11 tools for reading Harpd's open datasets — 1,122 AI
products, three Rank boards, 28 category boards, three Discovery Index slices,
the AI Market Index, published research and the Evidence Graph — over stdio,
with mandatory provenance on every single result.
git clone https://github.com/harpd-dev/harpd-mcp && cd harpd-mcp
npm install && npm run build
node examples/raw-stdio.mjs # zero-dependency proof it worksThe problem this solves
Harpd publishes its data openly at harpd.com/data and mirrors it to GitHub as raw JSON under CC BY 4.0. That is great for a developer who already knows the repository exists.
It is useless to an AI agent. An agent asked "which AI coding assistants are
listed, and can you back that up?" cannot curl a URL it has never heard of.
In practice the agent either says it has no data, or — far worse — answers from
training-data recall and states a confident, unsourced, possibly stale fact about
a product.
harpd-mcp closes that gap. It turns the datasets into callable tools, so the
agent retrieves the current record instead of remembering one.
Related MCP server: FirstData MCP
Why it exists
Three design decisions separate this from "wrap a JSON file in a tool":
1. Provenance is not optional. Every response — the envelope and every
record inside it — carries a provenance block with source, sourceUrl,
dataset (the file path), updatedAt, license, attribution and evidence.
There is no code path that returns a bare { name }. An agent that quotes Harpd
data can always say where it came from, when it was published, and under what
licence.
2. The two domain rules are encoded, not documented. They appear in the tool
descriptions the model actually reads, in the server instructions, and in a
machine-readable disclaimers array on every payload:
rankPointsare promotional placement bought with Credits on Harpd Rank. They are NOT an editorial quality score. Any tool that can order byrankPointssays so in its description and in its returned provenance.There is no multi-month ranking history in the dataset repository. Harpd publishes three live period-scoped snapshots.
get_ranking_historyreturns the periods that genuinely exist and states the limitation in the response itself. It will not fabricate a trend line.
3. Failure is graceful. A missing product or an unknown category returns a
structured found: false payload listing the valid options — not a crash and
not a stack trace in the model's context.
What data it uses
Read-only. Nothing is written back, and no API key is required.
Dataset file | Records | Served by |
| 1,122 |
|
| 1,122 |
|
| 1,122 |
|
| 1,122 |
|
| 28 |
|
| 27 |
|
| 334 |
|
| 693 |
|
| 1,918 |
|
| 5 |
|
| 5 claims |
|
| — | dataset metadata |
Record counts are read from the datasets themselves at runtime, not hard-coded.
Scope note. The product catalog is 1,122 records (
products.jsonand the three ranking boards). The research rows —ai-agent-index(334),ai-tools-index(693) anddeveloper-tools-index(1,918) — are separate coverage slices of the Harpd Discovery Index, not the product catalog. They are different datasets with their own sizes; only the catalog rows must equal the canonical product count. Full input/output reference:docs/tools.md.
How to run it
Requires Node.js >= 18.17.
git clone https://github.com/harpd-dev/harpd-mcp
cd harpd-mcp
npm install
npm run buildThen point any MCP stdio client at node /absolute/path/to/harpd-mcp/dist/index.js.
Environment variables
Variable | Default | Purpose |
|
| Where to read datasets from. Supports |
|
| On-disk cache TTL in milliseconds. |
|
| Cache location. |
The server fetches datasets from HARPD_DATA_BASE at runtime and caches them on
disk for the TTL. If a live fetch fails it falls back to the cached copy and adds
a warning to the response. A file:// base bypasses the cache entirely so local
runs are deterministic.
How to use the output
Every payload is one JSON text block shaped like this:
{
"tool": "search_products",
"found": true,
"query": { "query": "coding", "limit": 2 },
"pagination": { "total": 13, "count": 2, "offset": 0, "limit": 2, "hasMore": true, "nextOffset": 2 },
"results": [
{
"product": { "id": "github-copilot", "name": "GitHub Copilot", "rank": 11, "rankPoints": 0, "…": "…" },
"provenance": {
"source": "Harpd",
"sourceUrl": "https://raw.githubusercontent.com/…/data/products/products.json",
"dataset": "data/products/products.json",
"datasetId": "products",
"updatedAt": "2026-09-15T03:58:43.395Z",
"license": "CC BY 4.0",
"attribution": "Harpd (https://harpd.com)",
"evidence": {
"claimIds": [],
"methodologyUrl": "https://harpd.com/rank/methodology/",
"citation": "Harpd. \"products dataset.\" https://harpd.com/data/ Accessed: 2026-09-15. License: CC BY 4.0."
},
"notes": ["rankPoints are promotional placement bought with Credits on Harpd Rank. They are NOT an editorial quality score, …"]
}
}
],
"provenance": { "…": "same block, envelope level" },
"disclaimers": ["rankPoints are promotional placement bought with Credits on Harpd Rank. …"]
}Practical guidance:
Quote
provenance.sourceUrlandprovenance.updatedAtwhenever the agent repeats a figure. That is the difference between a sourced answer and a guess.Respect
disclaimers. They are returned precisely so they can be surfaced.Page with
pagination.nextOffset, not by guessing offsets.limitis capped at 200 by the input schema.Do not read
rankPointsas quality. If you need a non-purchasable signal, Harpd publishes one separately at harpd.com/data and says so in the Evidence Graph.
Tools
Tool | Purpose |
| Free-text / category search over the product catalog. |
| One product by id, slug or name. |
| Paginated catalog listing with filters. |
| A Rank board (overall / monthly / weekly) with its period metadata. |
| One of the 28 category boards, with board stats. |
| Compare the three board snapshots — and be told there is no time series. |
| AI-agent coverage slice (334 records). |
| AI-tools coverage slice (693 records). |
| Developer-tools coverage slice (1,918 records). |
| Monthly research reports + the AI Market Index. |
| The Evidence Graph: claims, chain, rules, and what Harpd does not claim. |
Client configuration
Verification status. This repository has verified the generic stdio client configurations below by actually running them (see
examples/—raw-stdio.mjsspeaks raw JSON-RPC with zero dependencies, and examples 1–5 use the official MCP SDK stdio client). The Claude Desktop, Cursor and VS Code sections are provided as configuration templates but are not verified in this repo — those applications were not available to launch and drive here, so no compatibility claim is made. Verify them yourself before relying on them.
Use absolute paths. Most clients do not inherit your shell PATH.
Generic stdio client — VERIFIED in this repo
Any client that can spawn a process and speak MCP over stdio:
{
"command": "node",
"args": ["/absolute/path/to/harpd-mcp/dist/index.js"],
"env": {
"HARPD_DATA_BASE": "https://raw.githubusercontent.com/harpd-dev/harpd-ai-datasets/main/"
}
}Verified two ways:
# 1. Raw JSON-RPC over stdio, zero dependencies (no MCP client library at all)
node examples/raw-stdio.mjs
# 2. Official MCP SDK stdio client
node examples/01-top-ai-coding-tools.mjsBoth were run against dist/index.js and returned real tool results. See the
Verification section for the exact output.
If you prefer the published package shape, the bin entry is harpd-mcp, so
once the package is published on npm the equivalent config is:
{ "command": "npx", "args": ["-y", "harpd-mcp"] }This package is not published to npm yet, so use the absolute-path form above for now. Publishing is a separate step and is not claimed here.
Claude Desktop — NOT VERIFIED in this repo
Config file: ~/Library/Application Support/Claude/claude_desktop_config.json
(macOS) or %APPDATA%\Claude\claude_desktop_config.json (Windows).
{
"mcpServers": {
"harpd": {
"command": "node",
"args": ["/absolute/path/to/harpd-mcp/dist/index.js"],
"env": {
"HARPD_DATA_BASE": "https://raw.githubusercontent.com/harpd-dev/harpd-ai-datasets/main/"
}
}
}
}Restart Claude Desktop after editing. The 11 tools appear under the tools icon.
Cursor — NOT VERIFIED in this repo
Project config .cursor/mcp.json, or global ~/.cursor/mcp.json:
{
"mcpServers": {
"harpd": {
"command": "node",
"args": ["/absolute/path/to/harpd-mcp/dist/index.js"]
}
}
}VS Code — NOT VERIFIED in this repo
Workspace config .vscode/mcp.json. Note that VS Code uses servers, not
mcpServers:
{
"servers": {
"harpd": {
"type": "stdio",
"command": "node",
"args": ["/absolute/path/to/harpd-mcp/dist/index.js"]
}
}
}Running offline
Point HARPD_DATA_BASE at a local checkout of the datasets. file:// bases
need a trailing slash:
git clone https://github.com/harpd-dev/harpd-ai-datasets
HARPD_DATA_BASE=file:///absolute/path/to/harpd-ai-datasets/ node dist/index.jsVerification
Everything below was run in this repository. The test suite runs against the real dataset files, never fixtures:
HARPD_DATA_BASE=file:///Users/shankou/harpd/harpd-ai-datasets/ npm test
# Test Files 2 passed (2)
# Tests 84 passed (84)Data Source
Harpd data portal: https://harpd.com/data/
Open dataset repository: https://github.com/harpd-dev/harpd-ai-datasets
Publisher: https://harpd.com/
License: CC BY 4.0 — attribution required
This server reads those files at runtime from
https://raw.githubusercontent.com/harpd-dev/harpd-ai-datasets/main/. It ships
no dataset copy of its own, so it cannot serve data that Harpd has not published.
Harpd Open AI Data Ecosystem
harpd-mcp is one client of the same open dataset that powers the rest of the
Harpd data surface. If you need the raw files, the CSV exports, the JSON Schemas
or the monthly snapshots, go straight to the source.
Harpd data portal — harpd.com/data — the canonical, citable entry point for every published dataset.
Harpd AI Datasets (GitHub) — github.com/harpd-dev/harpd-ai-datasets — raw JSON + CSV, JSON Schemas, validation scripts, starter templates and copy-paste examples in Python, JavaScript, curl, DuckDB, pandas and SQL.
Harpd Rank — harpd.com/rank — the boards these rankings come from, plus the published methodology.
Harpd Evidence — harpd.com/evidence — every published claim resolved to its evidence, dataset, methodology, source and timestamp.
Harpd research — harpd.com/research — the monthly index reports.
Harpd Discovery — harpd.com/discovery — the Product Discovery Index the agent / AI tools / developer tools slices are cut from.
harpd-mcp— this repository — the agent-facing MCP server for all of the above.
If you are building with the raw files rather than through an agent, use the datasets repository directly: it carries CSV exports, schemas and a daily sync workflow that this server does not duplicate.
Citation
If you use this server or the data behind it, cite Harpd:
@misc{harpd_data_2026,
title = {Harpd AI Datasets},
author = {{Harpd}},
year = {2026},
howpublished = {\url{https://harpd.com/data/}},
note = {Open datasets for AI products, rankings, research and evidence.
License: CC BY 4.0. Mirror: \url{https://github.com/harpd-dev/harpd-ai-datasets}}
}Plain text attribution string, as embedded in every dataset file:
Data from Harpd (https://harpd.com/)
If you cite this server specifically:
@software{harpd_mcp_2026,
title = {harpd-mcp: Model Context Protocol server for Harpd open AI datasets},
author = {{Harpd}},
year = {2026},
url = {https://github.com/harpd-dev/harpd-mcp},
note = {MIT licensed. Data licensed CC BY 4.0 by Harpd.}
}Machine-readable citation metadata is in CITATION.cff.
Development
npm run build # tsc -> dist/
npm run lint # eslint
npm test # vitest, against the real datasetsSee CONTRIBUTING.md and SECURITY.md.
License
Code: MIT — see
LICENSE.Data served by this server: CC BY 4.0, © Harpd. Attribution required. The MIT licence on this repository does not relicense the data.
Harpd is not affiliated with Anthropic, Cursor or Microsoft. MCP client names are used only to describe configuration formats.
Available Tools
11 toolsget_ai_agentsGet AI agents from the Harpd Discovery IndexARead-only
Return AI-agent products from the Harpd AI Agent Index (334 records, Discovery Index slice where category = "agents"). This is a COVERAGE list derived from the Harpd Product Discovery Index, NOT a ranking: records carry no rank and no rankPoints, and their order implies nothing about quality. Each record includes its observed_at timestamp, discovery source and profile URL. Use this to find AI agent products, their domains, one-line titles and where they were discovered. Some records also appear on the Harpd Rank board (on_rank_board). Every record carries full provenance (source, dataset path, sourceUrl, updatedAt, license, attribution).
Inputs: limit, query, domain, offset, +3 more.
get_ai_toolsGet AI tools from the Harpd Discovery IndexARead-only
Return AI tooling products from the Harpd AI Tools Index (693 records, Discovery Index slice where category is "agents" or "ai-media"). This is a COVERAGE list derived from the Harpd Product Discovery Index, NOT a ranking: records carry no rank and no rankPoints, and their order implies nothing about quality. Each record includes its observed_at timestamp, discovery source and profile URL. Use this to retrieve the current AI tools dataset: name, domain, URL, category, title, description, discovery source and observation timestamp. Every record carries full provenance (source, dataset path, sourceUrl, updatedAt, license, attribution).
Inputs: limit, query, domain, offset, +3 more.
get_category_rankingGet a Harpd category boardARead-only
Read one of the 28 published Harpd Rank category boards: the board metadata (product counts, state, board URL) plus the products listed in that category. CRITICAL: rankPoints are promotional placement bought with Credits on Harpd Rank, NOT an editorial quality score. A category board being "topRankOpen" or a product having high rankPoints says nothing about product quality. An unknown category returns a structured found:false result listing the valid slugs, not an error. Every record carries full provenance.
Inputs: category (required), sort, limit, offset.
get_developer_toolsGet developer tools from the Harpd Discovery IndexARead-only
Return developer-tool products from the Harpd Developer Tools Index (1,918 records, Discovery Index slice where category = "developer"). This is a COVERAGE list derived from the Harpd Product Discovery Index, NOT a ranking: records carry no rank and no rankPoints, and their order implies nothing about quality. Each record includes its observed_at timestamp, discovery source and profile URL. Use this to find developer tools, SDKs, infra and dev platforms by name, domain or description. Every record carries full provenance (source, dataset path, sourceUrl, updatedAt, license, attribution).
Inputs: limit, query, domain, offset, +3 more.
get_evidenceGet Harpd evidence claims for a dataset or productARead-only
Query the Harpd Evidence Graph: every published Harpd claim resolved to its evidence, dataset, methodology, source and data timestamp, including the claims Harpd explicitly does NOT make. Use this to check whether a statement about Harpd data is actually supported before repeating it. IMPORTANT: the graph itself records that rankPoints are promotional placement bought with Credits, and that "a higher-ranked product is a better product" is NOT a supported claim. rankPoints are NOT an editorial quality score. Claims that fail the evidence chain are returned with their violations rather than hidden. Every record carries full provenance.
Inputs: limit, query, offset, claimId, +4 more.
get_productGet one Harpd AI productARead-only
Look up a single product in the Harpd open product catalog by id, slug or name. Returns the product record plus mandatory provenance (source, dataset path, sourceUrl, updatedAt, license, attribution, evidence links). A product that does not exist returns a structured found:false result rather than an error. NOTE: rankPoints are promotional placement bought with Credits, NOT an editorial quality score.
Inputs: id, name, slug.
get_productsList Harpd AI products (paginated)ARead-only
Page through the full Harpd open product catalog (1,122 records) with filters on category, verification state, product type and rankPoints range. Use this to enumerate or bulk-export products; use search_products for free-text lookup. IMPORTANT: rankPoints are promotional placement bought with Credits on Harpd Rank, NOT an editorial quality score. Sorting by "rankPoints" orders by promotional placement, not by merit. Page size is capped at 200. Every record carries full provenance.
Inputs: sort, limit, offset, category, +4 more.
get_ranking_historyCompare Harpd board snapshots (NOT a time series)ARead-only
Compare the three published Harpd Rank board snapshots (overall / monthly / weekly) for one product, or side by side at board level. HONEST SCOPE WARNING: this repository publishes three LIVE period-scoped snapshots, each covering its current window. It does NOT contain a multi-month historical time series, so this tool cannot and will not return month-over-month trends. It returns the periods the datasets really expose plus an explicit statement of the limitation. CRITICAL: rankPoints are promotional placement bought with Credits on Harpd Rank, NOT an editorial quality score. Movement between boards reflects promotional placement, not a change in product quality.
Inputs: top, boards, productId, productSlug.
get_rankingsGet a Harpd Rank boardARead-only
Read one of the three published Harpd Rank boards (overall / monthly / weekly) with its period metadata. CRITICAL: rankPoints are promotional placement bought with Credits on Harpd Rank. They are NOT an editorial quality score, and a higher rankPoints value does NOT mean a better product. Ordering by "rankPoints" orders by promotional placement. Ordering by "rank" follows the published board position, which is also derived from promotional placement. The board is a live snapshot for its period, not a historical time series. Every record carries full provenance.
Inputs: sort, board, limit, offset, +1 more.
get_researchGet Harpd research reports and the AI market indexARead-only
Read Harpd research output: the published monthly research reports (5 records, one per family/month) and the AI Market Index (27 category rows with product counts, product share and rank-point share). IMPORTANT: pointsShare is a share of rankPoints, and rankPoints are promotional placement bought with Credits on Harpd Rank. They are NOT an editorial quality score. pointsShare is not a share of quality or of market merit. Reports exist only for closed months with enough ranked products in the family scope. Every record carries full provenance.
Inputs: limit, family, offset, section, +2 more.
search_productsSearch Harpd AI productsARead-only
Search the Harpd open product catalog (1,122 AI products) by free text, category and verification state. Returns each product with its board position (rank) and its rankPoints. IMPORTANT: rankPoints are promotional placement bought with Credits on Harpd Rank, NOT an editorial quality score. Ordering by rankPoints orders by promotional placement, not by merit. Every record carries full provenance (source, dataset path, updatedAt, license, attribution, evidence).
Inputs: sort, limit, query, offset, +2 more.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 11 tools
The catalog tools are clearly separated by mode (single lookup, free-text search, paged enumeration), and ranking, discovery-index, research, and evidence tools target distinct resources. The main overlap is between get_ai_agents and get_ai_tools, since one is a subset of the other's filter scope, but the descriptions do enough to clarify their different index purposes.
The naming pattern is mostly predictable: a get_ prefix followed by a domain noun, with search_products as the one clear exception. There is also some singular/plural inconsistency (get_product vs get_products, get_rankings vs get_category_ranking), but the overall convention remains readable and navigable.
Eleven tools is well within the ideal range and each tool maps to a meaningful data-access need: product lookup/search/enumeration, board reads, history comparison, three discovery-index slices, research, and evidence checking. None of the tools feel redundant or superfluous for the server's stated purpose.
The server covers the core read-only workflows for the Harpd domain: retrieving products, searching and enumerating them, reading rank boards, comparing snapshots, pulling discovery-index slices, and accessing research and evidence. Minor gaps include the lack of a dedicated category-list endpoint and the absence of search/detail operations within the discovery-index slices, but these are workable.
Maintenance
Related MCP Connectors
SEC filings, Wikipedia, arXiv, US Census and more for AI agents, with every answer source-linked.
Structured, cited, real-world data from 300+ sources and the open web for your AI agents.
Provable crypto data for AI agents: sourced checks on tokens, wallets and trades, with proof ids.
Query your AI agent traces, root-cause verdicts and issues, and run investigations, from your agent.
Related MCP Servers
- FlicenseNot gradedqualityAmaintenanceEnables users and AI agents to turn natural-language data queries into authoritative primary-source recommendations, complete with authority levels, access URLs/APIs, and step-by-step website navigation for retrieving verifiable data.-
- FlicenseNot gradedqualityAmaintenanceEnables users and AI agents to turn natural-language data questions into vetted authoritative source recommendations, with step-by-step website navigation, API details, and traceable evidence paths to primary data.-
- FlicenseNot gradedqualityAmaintenanceEnables users and AI agents to turn natural-language factual queries into recommended authoritative data sources and guided navigation paths for retrieving original datasets, APIs, and documents with verifiable evidence chains.-
- FlicenseNot gradedqualityAmaintenanceEnables AI agents and users to turn natural-language data questions into recommended authoritative primary sources and detailed, verified website/API retrieval paths with traceable evidence chains.-