MCP · REST API · SDKs

Connect your assistant

The server has one URL and needs no key or account. Add it to your client, then ask about a passage. Prefer plain HTTP or code? The REST API and the SDKs are further down.

https://translation-helps-mcp-v2.unfoldingword.workers.dev/v2/mcp

Claude Desktop

In Claude, open Settings, then Connectors, and choose Add custom connector. Paste the URL and give it a name. If your plan has no custom connectors, Claude Desktop can reach the server through mcp-remote in claude_desktop_config.json.

https://translation-helps-mcp-v2.unfoldingword.workers.dev/v2/mcp

Then ask, for example: “What do the notes say about ‘the world’ in John 3:16?” Or try it here first.

The REST API

The same data over plain HTTP: GET requests that answer in JSON, with no key. The MCP tools call this API underneath.

https://translation-helps-api-v2.unfoldingword.workers.dev/api/v1
curl "https://translation-helps-api-v2.unfoldingword.workers.dev/api/v1/scripture?reference=JHN%203:16&language=en"

Every endpoint, with its parameters and an example answer, is on the REST API page.

SDKs

A JavaScript and TypeScript client and a Python client wrap the MCP calls. Pass the server URL shown above.

These are the 2.0 clients, which are not on npm or PyPI yet. The packages there under the same names are the older 1.x clients, with other methods. Install 2.0 from the repository, as shown.

# The 2.0 client is not on npm yet: build it from the repository.
git clone --branch v2 https://github.com/unfoldingWord/translation-helps-mcp.git
cd translation-helps-mcp && npm install
npm run build --workspace packages/js-sdk

# Then, in your project:
npm install ../translation-helps-mcp/packages/js-sdk

import { TranslationHelpsClient } from "@translation-helps/mcp-client";

const client = new TranslationHelpsClient({ serverUrl: "https://translation-helps-mcp-v2.unfoldingword.workers.dev/v2/mcp" });
const passage = await client.getPassage({ reference: "John 3:16", language: "en" });

More in the SDKs page.

Troubleshooting

The client says it cannot connect

This server speaks MCP over Streamable HTTP at the URL above. A client that can only start local programs needs mcp-remote (see Other clients).

The server never shows up, and there is no error

Check the key name in your config file. Cursor and Claude Desktop read "mcpServers", VS Code reads "servers", and a server under the wrong key can be skipped without a warning.

A request from curl or a script fails

MCP over HTTP needs both content types in the Accept header: application/json, text/event-stream. For plain requests without MCP, use the REST API below.

“Rate limit exceeded”

The server allows 90 requests per minute from one address by default. Wait the number of seconds in the Retry-After header and try again.

An answer says the resource is not available

That language or book has no such resource yet. It is an answer, not an error: try English, or ask list_resources what the language has.

Limits and error codes are listed under Limits and errors.