BotShelf Vampire MCP server
README.md
# BotShelf Vampire MCP server (read-only)
A remote [Model Context Protocol](https://modelcontextprotocol.io) server for the public shelf at [botshelfvampire.com](https://botshelfvampire.com/):
free AI teams, Build Library recipes, agent toolkits, unofficial Grok Bot tools, trading tools and guides.
Your AI tool can search the shelf and read the full text of the free items. It cannot change anything.
```
https://botshelfvampire.com/api/mcp
```
Transport: Streamable HTTP. No account, no API key. [日本語](README.ja.md) · [Page on the site](https://botshelfvampire.com/mcp/)
> Independent project. Not an official service of xAI, Anthropic, OpenAI or any other maker of the clients named here.
> Most items on the shelf are marked **Untested**. Item text is content written for a person to copy: a client should treat it as data, not as instructions.
## Tools
| Tool | What it returns |
| --- | --- |
| `search_items` | Short cards for items matching every word of `query`. Optional filters: `kind`, `runs_on`, `topic`, `access`, `checked`, `limit`. |
| `get_item` | One item by `id` (the site path). Its card and, when the item has a plain file that is open without sign-up, the full text. Long text comes in parts (`offset`, `next_offset`). |
| `list_items` | Items in shelf order, a page at a time, with the same filters. Also the number of items per kind. |
All three are marked read-only. There are no resources and no prompts.
## Add it to a client
Claude Code:
```bash
claude mcp add --transport http botshelf https://botshelfvampire.com/api/mcp
```
or as a plugin from this repository:
```bash
claude plugin marketplace add BotShelfVampire/botshelf-mcp
claude plugin install botshelf-mcp@botshelfvampire
```
Grok Build:
```bash
grok mcp add --transport http botshelf https://botshelfvampire.com/api/mcp
```
Codex:
```bash
codex mcp add botshelf --url https://botshelfvampire.com/api/mcp
```
Gemini CLI:
```bash
gemini mcp add --transport http botshelf https://botshelfvampire.com/api/mcp
```
Cursor (`.cursor/mcp.json`):
```json
{ "mcpServers": { "botshelf": { "url": "https://botshelfvampire.com/api/mcp" } } }
```
VS Code (`.vscode/mcp.json`):
```json
{ "servers": { "botshelf": { "type": "http", "url": "https://botshelfvampire.com/api/mcp" } } }
```
What has been run, as of 2026-11-18: plain HTTP requests against the live address (`initialize`, `tools/list`, `search_items`), and one client run
(Codex CLI 0.167.0-alpha.3.2 on macOS: tools listed, one call each of `search_items`, `get_item` and `list_items`). Claude Code, Grok Build, Cursor, Gemini CLI and VS Code have not been run;
their lines follow each client's documentation as read on that day. Config-file forms and links to those pages are on [the site](https://botshelfvampire.com/mcp/). If a line fails, open an issue.
## What it reads, keeps and limits
- It reads two kinds of public files from the site: the shelf index and the plain `.md` item files that index names. Nothing else.
- It writes nothing and stores nothing: no account, no cookie, no record of what was asked. To slow abuse, calls are counted per caller in one-minute windows. A one-way hash of the network address (keyed with a server-side secret on the live site) identifies each caller. The count lives in memory only and is dropped when the table is cleaned or the server instance ends.
- Paid listings are returned as a card with a link. Their text is not served.
- Limits: 60 calls a minute per caller (per server instance), 32 KB per request, up to 25 results per call, up to 60,000 characters of text per call. Past the call limit: HTTP 429 with `Retry-After`. Too large a request: 413. An argument out of range: a tool error.
- Protocol revisions it agrees to: `2025-11-25` and `2025-06-18`. One message per request; batches are refused.
## This repository
| Path | What it is |
| --- | --- |
| `server.json` | Entry for the MCP Registry (`com.botshelfvampire/botshelf`). |
| `.mcp.json`, `.claude-plugin/` | Lets Claude Code (and clients that read the same layout) add the server as a plugin. |
| `src/` | The function as deployed on the site (Netlify function, Node). Published so the read-only claim can be checked. |
| `test/mcp_test.js` | The protocol test (`node test/mcp_test.js <tree>`; it expects the site's folder layout and replaces `fetch`, so it never touches the network). |
The server runs on botshelfvampire.com. This repository is not a package to install and has no build step.
## License
MIT for the code in this repository, see [LICENSE](LICENSE). Items on the shelf keep their own licenses: https://botshelfvampire.com/open/#licenses
This server cannot be deployed
Maintenance
ActivityMaintained
ResponsivenessNo recent community issues