Skip to content

Commit e02f4c5

Browse files
deloreyjdeloreyj
authored
feat: update README for workers-bindings mcp (cloudflare#120)
* feat: update README for workers-bindings mcp * feat: add CONTRIBUTING.md to workers-bindings --------- Co-authored-by: [email protected] <[email protected]>
1 parent c66e38f commit e02f4c5

File tree

3 files changed

+141
-101
lines changed

3 files changed

+141
-101
lines changed

‎apps/radar/README.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -41,7 +41,7 @@ This MCP server is still a work in progress, and we plan to add more tools in th
4141

4242
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/)).
4343

44-
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.
44+
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.
4545

4646
Replace the content with the following configuration:
4747

‎apps/workers-bindings/CONTRIBUTING.md‎

Lines changed: 65 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,65 @@
1+
# Setup
2+
3+
If you'd like to iterate and test your MCP server, you can do so in local development.
4+
5+
## Local Development
6+
7+
1. Create a `.dev.vars` file in your project root:
8+
9+
If you're a Cloudflare employee:
10+
11+
```
12+
CLOUDFLARE_CLIENT_ID=your_development_cloudflare_client_id
13+
CLOUDFLARE_CLIENT_SECRET=your_development_cloudflare_client_secret
14+
```
15+
16+
If you're an external contributor, you can provide a development API token:
17+
18+
```
19+
DEV_DISABLE_OAUTH=true
20+
DEV_CLOUDFLARE_EMAIL=your_cloudflare_email
21+
# This is your global api token
22+
DEV_CLOUDFLARE_API_TOKEN=your_development_api_token
23+
```
24+
25+
2. Start the local development server:
26+
27+
```bash
28+
npx wrangler dev
29+
```
30+
31+
3. To test locally, open Inspector, and connect to `http://localhost:8976/sse`.
32+
Once you follow the prompts, you'll be able to "List Tools". You can also connect with any MCP client.
33+
34+
## Deploying the Worker ( Cloudflare employees only )
35+
36+
Set secrets via Wrangler:
37+
38+
```bash
39+
npx wrangler secret put CLOUDFLARE_CLIENT_ID -e <ENVIRONMENT>
40+
npx wrangler secret put CLOUDFLARE_CLIENT_SECRET -e <ENVIRONMENT>
41+
```
42+
43+
## Set up a KV namespace
44+
45+
Create the KV namespace:
46+
47+
```bash
48+
npx wrangler kv namespace create "OAUTH_KV"
49+
```
50+
51+
Then, update the Wrangler file with the generated KV namespace ID.
52+
53+
## Deploy & Test
54+
55+
Deploy the MCP server to make it available on your workers.dev domain:
56+
57+
```bash
58+
npx wrangler deploy -e <ENVIRONMENT>
59+
```
60+
61+
Test the remote server using [Inspector](https://modelcontextprotocol.io/docs/tools/inspector):
62+
63+
```bash
64+
npx @modelcontextprotocol/inspector@latest
65+
```

‎apps/workers-bindings/README.md‎

Lines changed: 75 additions & 100 deletions
Original file line numberDiff line numberDiff line change
@@ -1,111 +1,86 @@
1-
# Remote MCP Server on Cloudflare
2-
3-
Let's get a remote MCP server up-and-running on Cloudflare Workers complete with OAuth login!
4-
5-
## Develop locally
6-
7-
```bash
8-
# clone the repository
9-
git clone [email protected]:cloudflare/ai.git
10-
11-
# install dependencies
12-
cd ai
13-
npm install
14-
15-
# run locally
16-
npx nx dev remote-mcp-server
17-
```
18-
19-
You should be able to open [`http://localhost:8787/`](http://localhost:8787/) in your browser
20-
21-
## Connect the MCP inspector to your server
22-
23-
To explore your new MCP api, you can use the [MCP Inspector](https://modelcontextprotocol.io/docs/tools/inspector).
24-
25-
- Start it with `npx @modelcontextprotocol/inspector`
26-
- [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"
27-
- You will navigate to a (mock) user/password login screen. Input any email and pass to login.
28-
- You should be redirected back to the MCP Inspector and you can now list and call any defined tools!
29-
30-
<div align="center">
31-
<img src="img/mcp-inspector-sse-config.png" alt="MCP Inspector with the above config" width="600"/>
32-
</div>
33-
34-
<div align="center">
35-
<img src="img/mcp-inspector-successful-tool-call.png" alt="MCP Inspector with after a tool call" width="600"/>
36-
</div>
37-
38-
## Connect Claude Desktop to your local MCP server
39-
40-
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.
41-
42-
Open the file in your text editor and replace it with this configuration:
43-
44-
```json
45-
{
46-
"mcpServers": {
47-
"math": {
48-
"command": "npx",
49-
"args": ["mcp-remote", "http://localhost:8787/sse"]
50-
}
51-
}
52-
}
53-
```
54-
55-
This will run a local proxy and let Claude talk to your MCP server over HTTP
56-
57-
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.
58-
59-
<div align="center">
60-
<img src="img/available-tools.png" alt="Clicking on the hammer icon shows a list of available tools" width="600"/>
61-
</div>
62-
63-
<div align="center">
64-
<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"/>
65-
</div>
66-
67-
## Deploy to Cloudflare
68-
69-
1. `npx wrangler kv namespace create OAUTH_KV`
70-
2. Follow the guidance to add the kv namespace ID to `wrangler.jsonc`
71-
3. `npm run deploy`
72-
73-
## Call your newly deployed remote MCP server from a remote MCP client
74-
75-
Just like you did above in "Develop locally", run the MCP inspector:
76-
77-
`npx @modelcontextprotocol/inspector@latest`
78-
79-
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".
80-
81-
You've now connected to your MCP server from a remote MCP client.
82-
83-
## Connect Claude Desktop to your remote MCP server
84-
85-
Update the Claude configuration file to point to your `workers.dev` URL (ex: `worker-name.account-name.workers.dev/sse`) and restart Claude
1+
# Cloudflare Workers Bindings MCP Server
2+
3+
This is a [Model Context Protocol (MCP)](https://modelcontextprotocol.io/introduction) server that supports remote MCP
4+
connections, with Cloudflare OAuth built-in.
5+
6+
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/).
7+
8+
## 🔨 Available Tools
9+
10+
Currently available tools:
11+
12+
| **Category** | **Tool** | **Description** |
13+
| ----------------- | -------------------------- | ----------------------------------------------------------------------------- |
14+
| **Account** | `accounts_list` | List all accounts in your Cloudflare account |
15+
| | `set_active_account` | Set active account to be used for tool calls that require accountId |
16+
| **KV Namespaces** | `kv_namespaces_list` | List all of the kv namespaces in your Cloudflare account |
17+
| | `kv_namespace_create` | Create a new kv namespace in your Cloudflare account |
18+
| | `kv_namespace_delete` | Delete a kv namespace in your Cloudflare account |
19+
| | `kv_namespace_get` | Get details of a kv namespace in your Cloudflare account |
20+
| | `kv_namespace_update` | Update the title of a kv namespace in your Cloudflare account |
21+
| **Workers** | `workers_list` | List all Workers in your Cloudflare account |
22+
| | `worker_get_worker` | Get the source code of a Cloudflare Worker |
23+
| **R2 Buckets** | `r2_buckets_list` | List r2 buckets in your Cloudflare account |
24+
| | `r2_bucket_create` | Create a new r2 bucket in your Cloudflare account |
25+
| | `r2_bucket_get` | Get details about a specific R2 bucket |
26+
| | `r2_bucket_delete` | Delete an R2 bucket |
27+
| **D1 Databases** | `d1_databases_list` | List all of the D1 databases in your Cloudflare account |
28+
| | `d1_database_create` | Create a new D1 database in your Cloudflare account |
29+
| | `d1_database_delete` | Delete a d1 database in your Cloudflare account |
30+
| | `d1_database_get` | Get a D1 database in your Cloudflare account |
31+
| | `d1_database_query` | Query a D1 database in your Cloudflare account |
32+
| **Hyperdrive** | `hyperdrive_configs_list` | List Hyperdrive configurations in your Cloudflare account |
33+
| | `hyperdrive_config_create` | Create a new Hyperdrive configuration in your Cloudflare account |
34+
| | `hyperdrive_config_delete` | Delete a Hyperdrive configuration in your Cloudflare account |
35+
| | `hyperdrive_config_get` | Get details of a specific Hyperdrive configuration in your Cloudflare account |
36+
| | `hyperdrive_config_edit` | Edit (patch) a Hyperdrive configuration in your Cloudflare account |
37+
38+
This MCP server is still a work in progress, and we plan to add more tools in the future.
39+
40+
### Prompt Examples
41+
42+
- `List my Cloudflare accounts.`
43+
- `Set my active account to 'YOUR_ACCOUNT_ID'.` (Replace YOUR_ACCOUNT_ID with an actual ID)
44+
- `Show me my KV namespaces.`
45+
- `Create a new KV namespace called 'my-kv-store'.`
46+
- `Get the details for KV namespace 'YOUR_NAMESPACE_ID'.` (Replace YOUR_NAMESPACE_ID)
47+
- `Delete the KV namespace 'NAMESPACE_TO_DELETE_ID'.` (Replace NAMESPACE_TO_DELETE_ID)
48+
- `List my Cloudflare Workers.`
49+
- `Get the code for the 'my-worker-script' worker.`
50+
- `Show me my R2 buckets.`
51+
- `Create an R2 bucket named 'my-new-bucket'.`
52+
- `Get details for the R2 bucket 'my-data-bucket'.`
53+
- `Delete the R2 bucket 'old-bucket'.`
54+
- `List my D1 databases.`
55+
- `Create a D1 database named 'analytics-db'.`
56+
- `Get details for D1 database 'YOUR_D1_DB_ID'.` (Replace YOUR_D1_DB_ID)
57+
- `Run the query 'SELECT * FROM customers LIMIT 10;' on D1 database 'YOUR_D1_DB_ID'.` (Replace YOUR_D1_DB_ID)
58+
- `Delete the D1 database 'TEMP_DB_ID'.` (Replace TEMP_DB_ID)
59+
- `List my Hyperdrive configurations.`
60+
- `Create a Hyperdrive config named 'prod-db-cache' for my database.` (You might need to provide more origin details)
61+
- `Get details for Hyperdrive config 'YOUR_HYPERDRIVE_ID'.` (Replace YOUR_HYPERDRIVE_ID)
62+
- `Update the cache settings for Hyperdrive config 'YOUR_HYPERDRIVE_ID'.` (Replace YOUR_HYPERDRIVE_ID)
63+
- `Delete the Hyperdrive config 'OLD_HYPERDRIVE_ID'.` (Replace OLD_HYPERDRIVE_ID)
64+
65+
## Access the remote MCP server from from any MCP Client
66+
67+
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/)).
68+
69+
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.
70+
71+
Replace the content with the following configuration:
8672

8773
```json
8874
{
8975
"mcpServers": {
90-
"math": {
76+
"cloudflare": {
9177
"command": "npx",
92-
"args": ["mcp-remote", "https://worker-name.account-name.workers.dev/sse"]
78+
"args": ["mcp-remote", "https://bindings.mcp.cloudflare.com/sse"]
9379
}
9480
}
9581
}
9682
```
9783

98-
## Debugging
84+
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.
9985

100-
Should anything go wrong it can be helpful to restart Claude, or to try connecting directly to your
101-
MCP server on the command line with the following command.
102-
103-
```bash
104-
npx mcp-remote http://localhost:8787/sse
105-
```
106-
107-
In some rare cases it may help to clear the files added to `~/.mcp-auth`
108-
109-
```bash
110-
rm -rf ~/.mcp-auth
111-
```
86+
Interested in contributing, and running this server locally? See [CONTRIBUTING.md](CONTRIBUTING.md) to get started.

0 commit comments

Comments
 (0)