Skip to main content
Glama
deenesjakoruzh
datavilleorg

dataville-mcp

by datavilleorg
OverviewSchemaSourceRelated ServersDiscussionsAdmin
TypeScript
Remote

dataville-mcp

Glama MCP server score M8ven Score npm CI License: MIT

Install in Cursor Install in VS Code

MCP server exposing Dataville's data source API as tools for MCP clients (Claude Desktop, Claude Code, etc.).

Dataville is a unified REST API over ten public datasets — Wikipedia, arXiv, Project Gutenberg, US Census, USDA FoodData, Papers with Code, SEC EDGAR, OpenAlex, PyPI, and Stack Exchange — behind one interface and one API key, with CSV/Parquet export and SQL query support. This package lets an MCP client search any of those sources as a tool call.

Requires a Dataville API key — get one from the Dataville dashboard.

Docs: docs.dataville.com · Connect an AI tool · Data sources. Examples: dataville-wikimedia, dataville-sec-edgar, company-intelligence-agent. Live demos: app.dataville.com/demos.

Tools

Tool

What it does

list_dataville_sources

Every source, with the SQL tables (if any) you can query for it.

describe_dataville_source

One source's keyword format, a working example, and its tables' columns: { source }.

search_dataville

Look one thing up by keywords and get the best match: { source, keywords, summary? }.

query_dataville

Read-only SQL SELECT over the stored tables for lists, filters, counts, joins, and paging with LIMIT/OFFSET: { sql }.

All four only read data. query_dataville covers every stored source except census and news, which are fetched live per search. It returns at most 1,000 rows per call and is billed per row returned. It reads Dataville's stored copy: some sources are loaded in bulk, others only hold records fetched before, so for one specific item search_dataville is the reliable route.

Related MCP server: Exasol MCP Server

What you can ask

Once connected, ask in plain language and the client picks the source:

  • "Find an arXiv paper on retrieval-augmented generation and summarize it."

  • "What did Apple report in its latest SEC filing?"

  • "What's the median household income in Travis County, Texas, per the US Census?"

  • "How much protein is in 100 g of cooked lentils, according to USDA FoodData?"

  • "Look up the requests package on PyPI — what's the latest version and license?"

  • "List ten Project Gutenberg books by Jane Austen, with their subjects."

  • "List five USDA FoodData entries with 'lentils' in the name, with their categories."

Setup

This package is a local (stdio) MCP server: the client launches it on your machine via npx. If you don't need it running locally, connecting to Dataville's hosted endpoint instead takes one line and no install.

Hosted, in one line (no install)

Dataville also serves MCP directly over HTTP, so a client can connect without running anything locally — no Node, no config file, no restart:

claude mcp add --transport http dataville https://api.dataville.com/mcp

That works with no credentials at all (anonymous limits). Add --header "Authorization: Bearer dataville_your_key_here" for the full quota. Cursor and VS Code users can use the install buttons at the top of this page. Other clients take the same URL; the app's Integrations page has the exact snippet for each. Use the hosted endpoint unless you specifically want to pin a version or work offline — the rest of this section covers that local setup.

Prerequisites

  • Node.js (LTS) installed — this is what runs npx. Without it the server fails to start. Check with node --version.

  • A Dataville API key — get one from https://app.dataville.com/api-keys.

The config block is the same everywhere; only where you put it differs:

{
  "mcpServers": {
    "dataville": {
      "command": "npx",
      "args": ["-y", "@dataville/dataville-mcp"],
      "env": {
        "DATAVILLE_API_KEY": "dataville_your_key_here"
      }
    }
  }
}

No install step needed — npx fetches and runs the package on demand.

Claude Desktop

  1. Open Settings → Developer → Edit Config. This opens claude_desktop_config.json:

    • macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

    • Windows: %APPDATA%\Claude\claude_desktop_config.json

  2. Add the block above (merge into mcpServers if the file already has one), with your real key.

  3. Fully quit and reopen Claude Desktop — quit from the menu bar / system tray, not just closing the window.

  4. The dataville tools now appear under the tools icon in the chat box, and Settings → Developer shows dataville running.

Note: the server appears as tools, not in the Connectors directory — that directory only lists remote (hosted) connectors and will not find a local server. Ask naturally ("get Apple's latest revenue from dataville") and the client calls the tool.

Claude Code

claude mcp add dataville -e DATAVILLE_API_KEY=dataville_your_key_here -- npx -y @dataville/dataville-mcp

Restart the session so the tools load. Add -s user to make it available in every project instead of just the current one.

Configuration

DATAVILLE_API_BASE_URL is optional and defaults to https://api.dataville.com; set it to http://localhost:5000 to point at a local backend during development.

Where your API key goes

The server reads DATAVILLE_API_KEY from its environment and sends it only as an Authorization: Bearer header to DATAVILLE_API_BASE_URL, which is https://api.dataville.com unless you change it. It never logs the key or sends it anywhere else. The base URL must use https. Plain http is accepted only for localhost, 127.0.0.1 and [::1], so the key never crosses the network unencrypted.

All four tools are read-only: they search and query Dataville and never create, change or delete anything.

Running from source

git clone https://github.com/datavilleorg/dataville-mcp.git
cd dataville-mcp
npm install
npm run build

Check that it works

Ask your client one of these. Each answer is checkable on purpose — a model that skipped the tool and answered from memory sounds just as confident, so a reply on its own proves nothing.

Ask

What proves it

Which data sources does Dataville have?

Calls list_dataville_sources and names all eleven.

Using Dataville, what is the latest version of the requests package on PyPI?

A version you can confirm on pypi.org — and it moves, so it can't come from memory.

Using Dataville, get the latest SEC filing for AAPL and its revenue.

A form type, filing date, revenue figure, and a sec.gov link to open.

Using Dataville, how much protein is in 100g of uncooked quinoa?

The exact USDA figure, 14.1 g per 100 g.

Using Dataville SQL, list 5 Project Gutenberg books by Mark Twain.

Calls query_dataville and returns titles with Gutenberg IDs you can open at gutenberg.org/ebooks/.

Clients show when a tool ran. If you don't see that, say "use dataville" in the prompt to make it explicit, and check the answer against the source.

Development

npm run dev    # tsx watch
npm test       # node test runner
npm run build  # tsc

Releasing

Publishes run from CI. npm uses trusted publishing (OIDC), so no npm token is stored; the MCP Registry step signs in with the MCP_PRIVATE_KEY repo secret. To cut a release: bump the version, update CHANGELOG.md, then publish a GitHub Release for the new tag. The Publish workflow builds, tests, and publishes to npm, then publishes server.json to the MCP Registry (its version is set from package.json, so don't bump it by hand).

The registry name com.dataville/dataville-mcp is authorized by a DNS TXT record on the dataville.com apex (v=MCPv1; k=ed25519; p=<public key>), checked against the Ed25519 private key in the MCP_PRIVATE_KEY repo secret (hex). If the mcp-registry job fails at login, check that record and secret, then re-run just that job.

Available Tools

4 tools
describe_dataville_sourceDescribe a Dataville data sourceA
Read-onlyIdempotent
Inspect

Show how to use one data source: what search_dataville expects as keywords (with an example that returns a result), and the SQL tables and columns query_dataville can read for it. Sources with no tables can only be searched.

ParametersJSON Schema
NameRequiredDescriptionDefault
sourceYesData source name from list_dataville_sources, e.g. 'edgar'

TDQS

A4/5.0
Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already declare readOnlyHint=true, idempotentHint=true, openWorldHint=false, destructiveHint=false, so the safety profile is covered. The description adds behavioral context about the payload (keyword example that returns a result, available tables/columns) and the read-only-search-only limitation. Useful but not rich beyond the annotations.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Two tight sentences with a compact parenthetical, front-loading what the tool shows. Every clause carries information; nothing is wasted.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

With no output schema, the description carries the burden of explaining the return contents and does so by naming the three payload categories (search keywords + example, tables, columns) and the no-tables limitation. It could say more about output structure/format, but it is sufficient for an agent to use the result.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

A single parameter with 100% schema description coverage; the schema already explains 'source' comes from list_dataville_sources with an example. The description adds no syntax or format detail beyond the schema, so the baseline 3 applies.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb+resource (describe one data source) and details exactly what it returns: search_dataville keyword expectations with an example, plus the SQL tables/columns query_dataville can read. It is clearly demarcated from the sibling search/query/list tools by naming them.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

By explaining that it reveals what search_dataville expects and what query_dataville can read, it implies this is the prerequisite reconnaissance call before those tools. It also notes a usage constraint ('sources with no tables can only be searched'). It stops short of an explicit 'call this before X' directive, so not a full 5.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

list_dataville_sourcesList Dataville data sourcesA
Read-onlyIdempotent
Inspect

List every Dataville data source with a one-line description and the SQL tables (if any) that query_dataville can read for it. Call describe_dataville_source for a source's keyword format and table columns.

ParametersJSON Schema
NameRequiredDescriptionDefault

No parameters

TDQS

A4.5/5.0
Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already declare readOnlyHint, idempotentHint, openWorldHint=false and destructiveHint=false, so safety is covered. The description adds genuinely useful behavior beyond that: it discloses the shape of what comes back (one-line descriptions plus tables) and that the tables are those query_dataville can read, which matters because there is no output schema.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Two sentences, both front-loaded: the return content first, the routing hint second. No filler, no restatement of the title.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Zero parameters, full annotation coverage, and no output schema, yet the description still explains what the listing contains and how results relate to query_dataville. An agent has everything needed to call it and to decide what to do next.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The tool takes no parameters, so the baseline is 4. There is nothing for the description to clarify or misstate, and it adds no spurious parameter-like guidance.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

States a specific verb (list) and resource (Dataville data sources), and specifies what each entry contains: a one-line description and the SQL tables readable by query_dataville. It also implicitly distinguishes itself from describe_dataville_source, which the agent is told to use for per-source detail.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The second sentence routes the agent to describe_dataville_source for keyword format and table columns, clarifying when this tool is not the right one. It lacks an explicit statement of when to prefer this tool over search_dataville, but the enumeration-vs-detail split is clear.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

query_datavilleQuery Dataville with SQLA
Read-onlyIdempotent
Inspect

Run a read-only SQL SELECT (DuckDB dialect) over Dataville's stored tables: wiki, arxiv, gutenberg, fooddata, pwc_methods, pwc_datasets, edgar, openalex, pypi, stackexchange. Use it to list, filter (WHERE … ILIKE '%term%'), sort, count, aggregate, or join across sources, and page through results with LIMIT/OFFSET. Get each table's columns from describe_dataville_source. Only SELECT is allowed; at most 1,000 rows are returned (a missing LIMIT becomes LIMIT 1000); queries time out after 30 s. Billed per row returned, so keep LIMIT as small as the task allows. The tables hold Dataville's stored copy: some sources are loaded in bulk, others only hold records fetched before, so a row missing here may still exist upstream — fall back to search_dataville for a specific item.

ParametersJSON Schema
NameRequiredDescriptionDefault
sqlYesA single SELECT statement, e.g. "SELECT company_name, form_type, filing_date FROM edgar WHERE company_name ILIKE '%apple%' ORDER BY filing_date DESC LIMIT 10"

TDQS

A4.9/5.0
Behavior5/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already establish readOnly/idempotent/no-destructive, and the description goes well beyond them: 1,000-row hard cap, implicit LIMIT 1000 when omitted, 30-second timeout, per-row billing, and the crucial staleness caveat that the tables are a stored copy with uneven upstream coverage. These are exactly the traits an agent needs to avoid surprise cost or missing data.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Front-loaded with purpose and table list, then progressively deeper operational constraints. Despite being a long single paragraph, every sentence carries a distinct constraint (cap, timeout, billing, staleness) with no filler.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

No output schema exists, and the description compensates by specifying the result envelope (max 1,000 rows, default LIMIT) and failure modes (timeout, stale/missing rows). Nothing an agent needs to call this correctly is absent.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

With a single parameter at 100% schema coverage, the baseline is 3, but the description adds real meaning: DuckDB dialect, the ILIKE '%term%' filtering idiom, LIMIT/OFFSET paging, and the SELECT-only constraint. That is genuine value beyond the schema's example string.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

Opens with a specific verb+resource (read-only SQL SELECT over Dataville's stored tables) and enumerates the exact table set, so an agent instantly knows the scope. It also implicitly distinguishes itself from list_dataville_sources, describe_dataville_source, and search_dataville by naming the latter two directly.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Explicitly states what the tool is good for (list, filter, sort, count, aggregate, join across sources), how to get schema first (describe_dataville_source), and the fallback condition (a row missing here may still exist upstream — use search_dataville for a specific item). When-to-use, prerequisite, and alternative are all covered.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

search_datavilleSearch a Dataville data sourceA
Read-onlyIdempotent
Inspect

Look up one thing in a Dataville data source by keywords and get back the single best-matching record (full text in body, structured fields in metadata). Use describe_dataville_source to see what keywords a source expects. To get many records, filter, or page through results, use query_dataville instead.

ParametersJSON Schema
NameRequiredDescriptionDefault
paramsNoExtra query-string parameters passed through to the API as-is. Most callers need none.
sourceYesData source name, e.g. 'wikipedia', 'arxiv', 'edgar' (see list_dataville_sources)
summaryNoIf true, truncate `body` to its first 100 characters to save tokens
keywordsYesSearch keywords or identifier, e.g. a title, ticker, or package name

TDQS

A4.5/5.0
Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already declare readOnlyHint, idempotentHint, openWorldHint, and non-destructive behavior, so safety is covered. The description adds genuine value beyond that: it discloses the cardinality (one record), the return structure (full text in `body`, fields in `metadata`), and that it is a passthrough-style lookup. It does not cover failure modes (e.g. no match found), keeping it short of a 5.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Three tight sentences, front-loaded with the core verb and cardinality, followed by return shape and then explicit alternatives. No sentence is redundant and no filler is present.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

With no output schema, the description compensates by naming the return fields (`body`, `metadata`) and cardinality. Combined with full parameter coverage and clear sibling routing, an agent has everything needed to invoke this correctly.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so all four parameters (source, keywords, params, summary) are already documented in the schema, making 3 the baseline. The description reinforces how keywords are chosen by pointing at describe_dataville_source, but adds no syntax or format detail beyond the schema.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

States a precise verb (look up) and resource (a Dataville data source) plus the exact scope: keywords in, single best-matching record out. It also disambiguates from query_dataville and describe_dataville_source by name, so an agent can pick it without opening any schema.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Explicitly routes the agent: use describe_dataville_source to learn what keywords a source expects, and use query_dataville when you need many records, filtering, or paging. The when-to-use and when-not-to-use conditions are both spelled out.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Tool Schema Changelog

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

  1. 3 tool updatesv0.1.8
    • Addeddescribe_dataville_source
    • Addedquery_dataville
    • Changedsearch_dataville6 fields changed
      • removedInput schema / additionalProperties
        Removed value: -false
      • changedInput schema / properties / keywords / description
        Previous value: -"Search keywords or identifier for the query"New value: +"Search keywords or identifier, e.g. a title, ticker, or package name"
      • changedInput schema / properties / params / description
        Previous value: -"Optional additional query parameters"New value: +"Extra query-string parameters passed through to the API as-is. Most callers need none."
      • addedInput schema / properties / params / propertyNames
        Added value: +{
+  "type": "string"
+}
      • changedInput schema / properties / source / description
        Previous value: -"Data source name, e.g. 'wikipedia', 'arxiv', 'edgar'"New value: +"Data source name, e.g. 'wikipedia', 'arxiv', 'edgar' (see list_dataville_sources)"
      • addedInput schema / properties / summary
        Added value: +{
+  "description": "If true, truncate `body` to its first 100 characters to save tokens",
+  "type": "boolean"
+}
  2. 2 tool updatesv0.1.0
    • First observedlist_dataville_sources
    • First observedsearch_dataville
Deploy Server
One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

TDQS

A4.3/5.0

Scored across 4 tools

Disambiguation5/5

Each tool targets a distinct phase of the workflow: list sources, describe a source, keyword search for one record, and SQL query for many records. The descriptions explicitly contrast search_dataville vs query_dataville, leaving no overlap.

Naming Consistency4/5

All names are snake_case with a clear verb prefix (list_, describe_, search_, query_), but the position of 'dataville' varies slightly (list_dataville_sources vs search_dataville). Still predictable and readable.

Tool Count4/5

Four tools is a lean but well-scoped set for a read-only data access server; each tool earns its place. It is slightly on the thin side (no dedicated fetch-by-id or schema tool), but nothing feels redundant.

Completeness4/5

Discovery (list/describe), retrieval (search), and flexible querying (SQL) cover the read-only domain well. Minor gap: no direct fetch-by-record identifier, though query_dataville can serve as a workaround.

Maintenance

ActivityMaintained
ResponsivenessNo issues

Resources

Related MCP Connectors

Related MCP Servers

  • Exasol MCP Server

    exasol
    -
    license
    Not graded
    quality
    A
    maintenance
    Provides an LLM access to the Exasol database via MCP tools, enabling reading of database metadata and execution of data reading queries.
    18
    -