Skip to content

feat: update README for workers-bindings mcp #120

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 2 commits into from
Apr 30, 2025
Merged

feat: update README for workers-bindings mcp #120

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
87ff82d
feat: update README for workers-bindings mcp
Apr 30, 2025
2b585e3
feat: add CONTRIBUTING.md to workers-bindings
deloreyj Apr 30, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 1 addition & 1 deletion apps/radar/README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -41,7 +41,7 @@ This MCP server is still a work in progress, and we plan to add more tools in th

If your MCP client has first class support for remote MCP servers, the client will provide a way to accept the server URL (`https://radar.mcp.cloudflare.com`) directly within its interface (for example in [Cloudflare AI Playground](https://playground.ai.cloudflare.com/)).

If your client does not yet support remote MCP servers, you will need to set up its resepective configuration file using [mcp-remote](https://www.npmjs.com/package/mcp-remote) to specify which servers your client can access.
If your client does not yet support remote MCP servers, you will need to set up its respective configuration file using [mcp-remote](https://www.npmjs.com/package/mcp-remote) to specify which servers your client can access.

Replace the content with the following configuration:

Expand Down
65 changes: 65 additions & 0 deletions apps/workers-bindings/CONTRIBUTING.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,65 @@
# Setup

If you'd like to iterate and test your MCP server, you can do so in local development.

## Local Development

1. Create a `.dev.vars` file in your project root:

If you're a Cloudflare employee:

```
CLOUDFLARE_CLIENT_ID=your_development_cloudflare_client_id
CLOUDFLARE_CLIENT_SECRET=your_development_cloudflare_client_secret
```

If you're an external contributor, you can provide a development API token:

```
DEV_DISABLE_OAUTH=true
DEV_CLOUDFLARE_EMAIL=your_cloudflare_email
# This is your global api token
DEV_CLOUDFLARE_API_TOKEN=your_development_api_token
```

2. Start the local development server:

```bash
npx wrangler dev
```

3. To test locally, open Inspector, and connect to `http://localhost:8976/sse`.
Once you follow the prompts, you'll be able to "List Tools". You can also connect with any MCP client.

## Deploying the Worker ( Cloudflare employees only )

Set secrets via Wrangler:

```bash
npx wrangler secret put CLOUDFLARE_CLIENT_ID -e <ENVIRONMENT>
npx wrangler secret put CLOUDFLARE_CLIENT_SECRET -e <ENVIRONMENT>
```

## Set up a KV namespace

Create the KV namespace:

```bash
npx wrangler kv namespace create "OAUTH_KV"
```

Then, update the Wrangler file with the generated KV namespace ID.

## Deploy & Test

Deploy the MCP server to make it available on your workers.dev domain:

```bash
npx wrangler deploy -e <ENVIRONMENT>
```

Test the remote server using [Inspector](https://modelcontextprotocol.io/docs/tools/inspector):

```bash
npx @modelcontextprotocol/inspector@latest
```
175 changes: 75 additions & 100 deletions apps/workers-bindings/README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,111 +1,86 @@
# Remote MCP Server on Cloudflare

Let's get a remote MCP server up-and-running on Cloudflare Workers complete with OAuth login!

## Develop locally

```bash
# clone the repository
git clone [email protected]:cloudflare/ai.git

# install dependencies
cd ai
npm install

# run locally
npx nx dev remote-mcp-server
```

You should be able to open [`http://localhost:8787/`](http://localhost:8787/) in your browser

## Connect the MCP inspector to your server

To explore your new MCP api, you can use the [MCP Inspector](https://modelcontextprotocol.io/docs/tools/inspector).

- Start it with `npx @modelcontextprotocol/inspector`
- [Within the inspector](http://localhost:5173), switch the Transport Type to `SSE` and enter `http://localhost:8787/sse` as the URL of the MCP server to connect to, and click "Connect"
- You will navigate to a (mock) user/password login screen. Input any email and pass to login.
- You should be redirected back to the MCP Inspector and you can now list and call any defined tools!

<div align="center">
<img src="img/mcp-inspector-sse-config.png" alt="MCP Inspector with the above config" width="600"/>
</div>

<div align="center">
<img src="img/mcp-inspector-successful-tool-call.png" alt="MCP Inspector with after a tool call" width="600"/>
</div>

## Connect Claude Desktop to your local MCP server

The MCP inspector is great, but we really want to connect this to Claude! Follow [Anthropic's Quickstart](https://modelcontextprotocol.io/quickstart/user) and within Claude Desktop go to Settings > Developer > Edit Config to find your configuration file.

Open the file in your text editor and replace it with this configuration:

```json
{
"mcpServers": {
"math": {
"command": "npx",
"args": ["mcp-remote", "http://localhost:8787/sse"]
}
}
}
```

This will run a local proxy and let Claude talk to your MCP server over HTTP

When you open Claude a browser window should open and allow you to login. You should see the tools available in the bottom right. Given the right prompt Claude should ask to call the tool.

<div align="center">
<img src="img/available-tools.png" alt="Clicking on the hammer icon shows a list of available tools" width="600"/>
</div>

<div align="center">
<img src="img/claude-does-math-the-fancy-way.png" alt="Claude answers the prompt 'I seem to have lost my calculator and have run out of fingers. Could you use the math tool to add 23 and 19?' by invoking the MCP add tool" width="600"/>
</div>

## Deploy to Cloudflare

1. `npx wrangler kv namespace create OAUTH_KV`
2. Follow the guidance to add the kv namespace ID to `wrangler.jsonc`
3. `npm run deploy`

## Call your newly deployed remote MCP server from a remote MCP client

Just like you did above in "Develop locally", run the MCP inspector:

`npx @modelcontextprotocol/inspector@latest`

Then enter the `workers.dev` URL (ex: `worker-name.account-name.workers.dev/sse`) of your Worker in the inspector as the URL of the MCP server to connect to, and click "Connect".

You've now connected to your MCP server from a remote MCP client.

## Connect Claude Desktop to your remote MCP server

Update the Claude configuration file to point to your `workers.dev` URL (ex: `worker-name.account-name.workers.dev/sse`) and restart Claude
# Cloudflare Workers Bindings MCP Server

This is a [Model Context Protocol (MCP)](https://modelcontextprotocol.io/introduction) server that supports remote MCP
connections, with Cloudflare OAuth built-in.

It integrates tools for managing resources in the Cloudflare Workers Platform, which you can connect to your Worker via [Bindings](https://developers.cloudflare.com/workers/runtime-apis/bindings/).

## 🔨 Available Tools

Currently available tools:

| **Category** | **Tool** | **Description** |
| ----------------- | -------------------------- | ----------------------------------------------------------------------------- |
| **Account** | `accounts_list` | List all accounts in your Cloudflare account |
| | `set_active_account` | Set active account to be used for tool calls that require accountId |
| **KV Namespaces** | `kv_namespaces_list` | List all of the kv namespaces in your Cloudflare account |
| | `kv_namespace_create` | Create a new kv namespace in your Cloudflare account |
| | `kv_namespace_delete` | Delete a kv namespace in your Cloudflare account |
| | `kv_namespace_get` | Get details of a kv namespace in your Cloudflare account |
| | `kv_namespace_update` | Update the title of a kv namespace in your Cloudflare account |
| **Workers** | `workers_list` | List all Workers in your Cloudflare account |
| | `worker_get_worker` | Get the source code of a Cloudflare Worker |
| **R2 Buckets** | `r2_buckets_list` | List r2 buckets in your Cloudflare account |
| | `r2_bucket_create` | Create a new r2 bucket in your Cloudflare account |
| | `r2_bucket_get` | Get details about a specific R2 bucket |
| | `r2_bucket_delete` | Delete an R2 bucket |
| **D1 Databases** | `d1_databases_list` | List all of the D1 databases in your Cloudflare account |
| | `d1_database_create` | Create a new D1 database in your Cloudflare account |
| | `d1_database_delete` | Delete a d1 database in your Cloudflare account |
| | `d1_database_get` | Get a D1 database in your Cloudflare account |
| | `d1_database_query` | Query a D1 database in your Cloudflare account |
| **Hyperdrive** | `hyperdrive_configs_list` | List Hyperdrive configurations in your Cloudflare account |
| | `hyperdrive_config_create` | Create a new Hyperdrive configuration in your Cloudflare account |
| | `hyperdrive_config_delete` | Delete a Hyperdrive configuration in your Cloudflare account |
| | `hyperdrive_config_get` | Get details of a specific Hyperdrive configuration in your Cloudflare account |
| | `hyperdrive_config_edit` | Edit (patch) a Hyperdrive configuration in your Cloudflare account |

This MCP server is still a work in progress, and we plan to add more tools in the future.

### Prompt Examples

- `List my Cloudflare accounts.`
- `Set my active account to 'YOUR_ACCOUNT_ID'.` (Replace YOUR_ACCOUNT_ID with an actual ID)
- `Show me my KV namespaces.`
- `Create a new KV namespace called 'my-kv-store'.`
- `Get the details for KV namespace 'YOUR_NAMESPACE_ID'.` (Replace YOUR_NAMESPACE_ID)
- `Delete the KV namespace 'NAMESPACE_TO_DELETE_ID'.` (Replace NAMESPACE_TO_DELETE_ID)
- `List my Cloudflare Workers.`
- `Get the code for the 'my-worker-script' worker.`
- `Show me my R2 buckets.`
- `Create an R2 bucket named 'my-new-bucket'.`
- `Get details for the R2 bucket 'my-data-bucket'.`
- `Delete the R2 bucket 'old-bucket'.`
- `List my D1 databases.`
- `Create a D1 database named 'analytics-db'.`
- `Get details for D1 database 'YOUR_D1_DB_ID'.` (Replace YOUR_D1_DB_ID)
- `Run the query 'SELECT * FROM customers LIMIT 10;' on D1 database 'YOUR_D1_DB_ID'.` (Replace YOUR_D1_DB_ID)
- `Delete the D1 database 'TEMP_DB_ID'.` (Replace TEMP_DB_ID)
- `List my Hyperdrive configurations.`
- `Create a Hyperdrive config named 'prod-db-cache' for my database.` (You might need to provide more origin details)
- `Get details for Hyperdrive config 'YOUR_HYPERDRIVE_ID'.` (Replace YOUR_HYPERDRIVE_ID)
- `Update the cache settings for Hyperdrive config 'YOUR_HYPERDRIVE_ID'.` (Replace YOUR_HYPERDRIVE_ID)
- `Delete the Hyperdrive config 'OLD_HYPERDRIVE_ID'.` (Replace OLD_HYPERDRIVE_ID)

## Access the remote MCP server from from any MCP Client

If your MCP client has first class support for remote MCP servers, the client will provide a way to accept the server URL (`https://bindings.mcp.cloudflare.com`) directly within its interface (for example in [Cloudflare AI Playground](https://playground.ai.cloudflare.com/)).

If your client does not yet support remote MCP servers, you will need to set up its respective configuration file using [mcp-remote](https://www.npmjs.com/package/mcp-remote) to specify which servers your client can access.

Replace the content with the following configuration:

```json
{
"mcpServers": {
"math": {
"cloudflare": {
"command": "npx",
"args": ["mcp-remote", "https://worker-name.account-name.workers.dev/sse"]
"args": ["mcp-remote", "https://bindings.mcp.cloudflare.com/sse"]
}
}
}
```

## Debugging
Once you've set up your configuration file, restart MCP client and a browser window will open showing your OAuth login page. Proceed through the authentication flow to grant the client access to your MCP server. After you grant access, the tools will become available for you to use.

Should anything go wrong it can be helpful to restart Claude, or to try connecting directly to your
MCP server on the command line with the following command.

```bash
npx mcp-remote http://localhost:8787/sse
```

In some rare cases it may help to clear the files added to `~/.mcp-auth`

```bash
rm -rf ~/.mcp-auth
```
Interested in contributing, and running this server locally? See [CONTRIBUTING.md](CONTRIBUTING.md) to get started.
Loading