Datacircle MCP Server
by waynehamadi
README.md
# Datacircle tools for the MCP TypeScript SDK
Find the best GTM APIs. We benchmark all the GTM APIs and we put the results on our website.
Our website: https://datacircle.dev
This package gives four MCP tools that call Datacircle's open API, https://api.datacircle.dev/v1. You can run them as a stdio MCP server in any MCP client. Or you can add them to your own server built with the [MCP TypeScript SDK](https://github.com/modelcontextprotocol/typescript-sdk). You need no key and no account.
| Tool | What the tool gives | Call |
| --- | --- | --- |
| `list_apis` | Every GTM API on Datacircle, with the API's slug, number of plans, number of providers and best plan | `GET /apis` |
| `best_plans` | One API's plans, best score out of 100 first. Each plan comes with a rank and a price per 1,000 calls | `GET /apis/{slug}/best` |
| `search_plans` | Plans that match a provider or plan name, on all APIs or on one API. You can sort them by score, provider or price | `GET /plans` |
| `provider_ranks` | The APIs a provider sells, and the provider's rank on each API | `GET /providers/{slug}` |
## Use it in an MCP client
Add the server to your client's MCP config. The client starts it with `npx`:
```json
{
"mcpServers": {
"datacircle": {
"command": "npx",
"args": ["-y", "@datacircle/mcp"]
}
}
}
```
The server needs Node.js 20 or later. It speaks both the 2026-07-28 MCP spec and the 2025 versions, so new and old clients can use it.
A client that connects to servers by URL can use our hosted MCP server instead, https://api.datacircle.dev/mcp, with nothing to install.
To try the server without a client, use the MCP Inspector:
```bash
npx @modelcontextprotocol/inspector --cli npx -y @datacircle/mcp --method tools/call --tool-name best_plans --tool-arg slug=email-finder
```
## Add the tools to your server
```bash
npm install @datacircle/mcp zod
```
With v2 of the SDK (`@modelcontextprotocol/server`):
```ts
import { McpServer } from '@modelcontextprotocol/server';
import { serveStdio } from '@modelcontextprotocol/server/stdio';
import { registerDatacircleTools } from '@datacircle/mcp';
serveStdio(() => {
const server = new McpServer({ name: 'my-server', version: '1.0.0' });
registerDatacircleTools(server);
// Register your own tools here too.
return server;
});
```
With v1 of the SDK (`@modelcontextprotocol/sdk` 1.23.0 or later):
```ts
import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
import { registerDatacircleTools } from '@datacircle/mcp';
const server = new McpServer({ name: 'my-server', version: '1.0.0' });
registerDatacircleTools(server);
await server.connect(new StdioServerTransport());
```
`registerDatacircleTools` returns each tool's `RegisteredTool`, in the order of the table, so you can disable or remove a tool later. The tools work with zod 4, and with zod 3.25 on v1 of the SDK. The package is ESM.
To add only some of the tools, name them: `registerDatacircleTools(server, { tools: ['best_plans', 'search_plans'] })`. To register the tools yourself, `datacircleTools()` gives each tool's `name`, `config` and `handler`, for `server.registerTool(name, config, handler)`.
## Make each call yourself
You can make each call without a server. Each call returns the answer as an object:
```ts
import { bestPlans } from '@datacircle/mcp';
const answer = await bestPlans({ slug: 'email-finder', limit: 3 });
console.log(answer.plans);
```
The other calls are `listApis()`, `searchPlans()` and `providerRanks()`.
## What the model reads
Each tool gives the model a JSON object as text. Each plan comes with a rank, provider, plan, score, price per 1,000 (`perThousand`, in dollars) and a page on datacircle.dev. The page on datacircle.dev lists every field.
An unknown slug, or a call with no data on the API, gets an error (`isError`) with the API's message. If an input does not fit the schema, the SDK returns an error that names each wrong argument. If the network fails, the model gets an error (`isError`) with the network error's message. After an error, the model can call the tool again and keep working. When the client cancels a call, the tool's request stops too.
`registerDatacircleTools(server, { fetch })` sets the `fetch` the tools use, for example to add a proxy or a timeout. To make a call from your code with your own `fetch`, pass `{ fetch }` as the call's second argument, like `bestPlans({ slug: 'serp' }, { fetch })`.
## Network
Each tool call makes one HTTPS GET request to https://api.datacircle.dev/v1 and nothing else. The request holds only the tool's own arguments: no key and nothing from your chats. The API takes up to 60 calls a minute from one IP address. After a 429 answer (too many calls), the tool waits up to a minute and tries once more. The package depends only on the SDK's server package and zod. The package stores nothing.
## Links
- Datacircle: https://datacircle.dev
- The API: https://datacircle.dev/api
- The API's spec: https://api.datacircle.dev/v1/openapi.json
- What each key means: https://datacircle.dev/fields
MIT license.
This server cannot be deployed
Maintenance
ActivityMaintained
ResponsivenessNo recent community issues