From 784c48a38bf0280942e56c7f3854124a69d2c5c6 Mon Sep 17 00:00:00 2001 From: Jacques Wainwright Date: Sun, 25 May 2025 09:23:29 +0200 Subject: [PATCH 1/4] Initial setup: MCP proxy configuration with examples and documentation - Add comprehensive MCP proxy setup for centralized server management - Include example configurations for proxy and Claude Desktop - Add startup script for easy proxy management - Provide detailed documentation and troubleshooting guide - Configure security features with tool filtering and auth tokens - Support for popular MCP servers: github, filesystem, puppeteer, memory, etc. --- .gitignore | 178 ++++++------------------ README-SETUP.md | 167 ++++++++++++++++++++++ README.md | 276 ++++++++++++++++++++++--------------- claude-config.example.json | 12 ++ proxy-config.example.json | 197 ++++++++++++++++++++++++++ start-proxy.sh | 16 +++ 6 files changed, 598 insertions(+), 248 deletions(-) create mode 100644 README-SETUP.md create mode 100644 claude-config.example.json create mode 100644 proxy-config.example.json create mode 100755 start-proxy.sh diff --git a/.gitignore b/.gitignore index 536bd99..4ec9b54 100644 --- a/.gitignore +++ b/.gitignore @@ -1,144 +1,48 @@ -# Created by https://www.toptal.com/developers/gitignore/api/goland,go -# Edit at https://www.toptal.com/developers/gitignore?templates=goland,go - -### Go ### -# If you prefer the allow list template instead of the deny list, see community template: -# https://github.com/github/gitignore/blob/main/community/Golang/Go.AllowList.gitignore -# -# Binaries for programs and plugins +# Binaries +build/ *.exe -*.exe~ *.dll *.so *.dylib -# Test binary, built with `go test -c` +# Environment variables and secrets +.env +*.key +*.pem + +# OS generated files +.DS_Store +.DS_Store? +._* +.Spotlight-V100 +.Trashes +ehthumbs.db +Thumbs.db + +# IDE files +.vscode/ +.idea/ +*.swp +*.swo +*~ + +# Logs +*.log +logs/ + +# Temporary files +tmp/ +temp/ + +# Node modules (if any) +node_modules/ + +# Go specific *.test +*.prof +vendor/ -# Output of the go coverage tool, specifically when used with LiteIDE -*.out - -# Dependency directories (remove the comment below to include it) -# vendor/ - -# Go workspace file -go.work - -### GoLand ### -# Covers JetBrains IDEs: IntelliJ, RubyMine, PhpStorm, AppCode, PyCharm, CLion, Android Studio, WebStorm and Rider -# Reference: https://intellij-support.jetbrains.com/hc/en-us/articles/206544839 - -# User-specific stuff -.idea/**/workspace.xml -.idea/**/tasks.xml -.idea/**/usage.statistics.xml -.idea/**/dictionaries -.idea/**/shelf - -# AWS User-specific -.idea/**/aws.xml - -# Generated files -.idea/**/contentModel.xml - -# Sensitive or high-churn files -.idea/**/dataSources/ -.idea/**/dataSources.ids -.idea/**/dataSources.local.xml -.idea/**/sqlDataSources.xml -.idea/**/dynamic.xml -.idea/**/uiDesigner.xml -.idea/**/dbnavigator.xml - -# Gradle -.idea/**/gradle.xml -.idea/**/libraries - -# Gradle and Maven with auto-import -# When using Gradle or Maven with auto-import, you should exclude module files, -# since they will be recreated, and may cause churn. Uncomment if using -# auto-import. -# .idea/artifacts -# .idea/compiler.xml -# .idea/jarRepositories.xml -# .idea/modules.xml -# .idea/*.iml -# .idea/modules -# *.iml -# *.ipr - -# CMake -cmake-build-*/ - -# Mongo Explorer plugin -.idea/**/mongoSettings.xml - -# File-based project format -*.iws - -# IntelliJ -out/ - -# mpeltonen/sbt-idea plugin -.idea_modules/ - -# JIRA plugin -atlassian-ide-plugin.xml - -# Cursive Clojure plugin -.idea/replstate.xml - -# SonarLint plugin -.idea/sonarlint/ - -# Crashlytics plugin (for Android Studio and IntelliJ) -com_crashlytics_export_strings.xml -crashlytics.properties -crashlytics-build.properties -fabric.properties - -# Editor-based Rest Client -.idea/httpRequests - -# Android studio 3.1+ serialized cache file -.idea/caches/build_file_checksums.ser - -### GoLand Patch ### -# Comment Reason: https://github.com/joeblau/gitignore.io/issues/186#issuecomment-215987721 - -# *.iml -# modules.xml -# .idea/misc.xml -# *.ipr - -# Sonarlint plugin -# https://plugins.jetbrains.com/plugin/7973-sonarlint -.idea/**/sonarlint/ - -# SonarQube Plugin -# https://plugins.jetbrains.com/plugin/7238-sonarqube-community-plugin -.idea/**/sonarIssues.xml - -# Markdown Navigator plugin -# https://plugins.jetbrains.com/plugin/7896-markdown-navigator-enhanced -.idea/**/markdown-navigator.xml -.idea/**/markdown-navigator-enh.xml -.idea/**/markdown-navigator/ - -# Cache file creation bug -# See https://youtrack.jetbrains.com/issue/JBR-2257 -.idea/$CACHE_FILE$ - -# CodeStream plugin -# https://plugins.jetbrains.com/plugin/12206-codestream -.idea/codestream.xml - -# Azure Toolkit for IntelliJ plugin -# https://plugins.jetbrains.com/plugin/8053-azure-toolkit-for-intellij -.idea/**/azureSettings.xml - -# End of https://www.toptal.com/developers/gitignore/api/goland,go - - -/mcp-proxy -/build \ No newline at end of file +# Configuration with sensitive data (we'll create sanitized versions) +# Uncomment these if you want to exclude configs with API keys +# proxy-config.json +# claude-config.json diff --git a/README-SETUP.md b/README-SETUP.md new file mode 100644 index 0000000..672ab75 --- /dev/null +++ b/README-SETUP.md @@ -0,0 +1,167 @@ +# Jacques' MCP Proxy Setup + +## ๐ŸŽฏ What This Is + +This MCP (Model Context Protocol) proxy centralizes **all your MCP servers** into a single interface that Claude can connect to. Instead of managing 15+ individual MCP server connections, Claude now only needs to connect to **one proxy server** that handles everything. + +## ๐Ÿ—๏ธ Architecture + +``` +Claude Desktop โ†’ MCP Proxy โ†’ Your Individual MCP Servers + โ†“ + [brave-search, github, filesystem, puppeteer, + memory, sequential-thinking, git, iterm, + n8n, obsidian, whatsapp, browser-tools] +``` + +## ๐Ÿ“ Files Created + +- `proxy-config.json` - Configuration for all your MCP servers +- `claude-config.json` - Simplified Claude Desktop configuration +- `start-proxy.sh` - Easy startup script +- `build/mcp-proxy` - The compiled proxy server binary + +## ๐Ÿš€ Quick Start + +### 1. Start the Proxy Server +```bash +cd /Users/jacques/DevFolder/mcp-proxy +./start-proxy.sh +``` + +### 2. Update Claude Desktop Configuration + +Replace your current `claude_desktop_config.json` with the contents of `claude-config.json`: + +**Location**: `~/Library/Application Support/Claude/claude_desktop_config.json` + +```bash +# Backup your current config +cp "~/Library/Application Support/Claude/claude_desktop_config.json" "~/Library/Application Support/Claude/claude_desktop_config.json.backup" + +# Copy the new simplified config +cp "/Users/jacques/DevFolder/mcp-proxy/claude-config.json" "~/Library/Application Support/Claude/claude_desktop_config.json" +``` + +### 3. Restart Claude Desktop + +## ๐Ÿ”ง Configuration Details + +### Proxy Settings +- **URL**: http://localhost:9090 +- **Auth Token**: `mcp-proxy-token-2025` +- **Tool Filtering**: Enabled with allow-lists for security + +### Included MCP Servers +- **brave-search**: Web search capabilities +- **github**: GitHub repository management +- **filesystem**: File system access with safe paths +- **puppeteer**: Browser automation +- **memory**: Knowledge graph and memory +- **sequential-thinking**: Step-by-step reasoning +- **git**: Git repository operations +- **iterm**: Terminal integration +- **n8n**: Workflow automation +- **obsidian**: Note management +- **whatsapp**: WhatsApp integration +- **browser-tools**: Browser development tools + +## ๐Ÿ”’ Security Features + +- **Tool Filtering**: Each server has explicit allow-lists of permitted tools +- **Authentication**: Uses auth tokens for proxy access +- **Safe Paths**: Filesystem access restricted to approved directories only +- **Environment Isolation**: Each MCP server runs in its own process + +## ๐Ÿ› ๏ธ Management Commands + +### Start Proxy +```bash +cd /Users/jacques/DevFolder/mcp-proxy +./start-proxy.sh +``` + +### Stop Proxy +Press `Ctrl+C` in the terminal running the proxy + +### Check Status +Visit: http://localhost:9090/health (if health endpoint exists) + +### View Logs +The proxy outputs detailed logs showing: +- Server connections +- Tool registrations +- Request routing +- Error debugging + +## ๐Ÿ”ง Customization + +### Adding New MCP Servers +Edit `proxy-config.json` and add to the `mcpServers` section: + +```json +"your-new-server": { + "command": "npx", + "args": ["-y", "your-mcp-package"], + "env": { + "API_KEY": "your-api-key" + }, + "options": { + "toolFilter": { + "mode": "allow", + "list": ["tool1", "tool2"] + } + } +} +``` + +### Removing Servers +Simply delete the server entry from `proxy-config.json` + +### Updating Tool Filters +Modify the `toolFilter.list` arrays to add/remove allowed tools + +## ๐Ÿšจ Troubleshooting + +### Proxy Won't Start +- Check if port 9090 is available: `lsof -i :9090` +- Verify all MCP commands are installed (npx, uvx, etc.) +- Check file paths in configuration + +### Claude Can't Connect +- Ensure proxy is running: `./start-proxy.sh` +- Verify claude-config.json is in the right location +- Restart Claude Desktop after config changes + +### Individual Servers Failing +- Check the proxy logs for specific error messages +- Verify environment variables and API keys +- Test individual servers directly if needed + +### Missing Tools +- Check proxy logs for "Adding tool" messages +- Verify tool names in toolFilter lists match exactly +- Some servers may need additional setup or API keys + +## ๐ŸŽ‰ Benefits + +โœ… **Simplified Management**: One config file instead of 15+ +โœ… **Better Security**: Centralized tool filtering and access control +โœ… **Easier Debugging**: Single log output for all servers +โœ… **Performance**: Reduced Claude startup time +โœ… **Maintainability**: Easy to add/remove servers +โœ… **Reliability**: Failed servers don't break others + +## ๐Ÿ“ž Support + +If you need to modify this setup: +1. Edit `proxy-config.json` for server changes +2. Run `./start-proxy.sh` to restart +3. Check logs for any issues +4. Update tool filters as needed + +--- + +**Created**: May 25, 2025 +**Version**: 1.0 +**Proxy**: TBXark/mcp-proxy v1.0.0 diff --git a/README.md b/README.md index 02d937a..9bbb2aa 100644 --- a/README.md +++ b/README.md @@ -1,166 +1,220 @@ -# MCP Proxy Server +# MCP Proxy Setup -An MCP proxy server that aggregates and serves multiple MCP resource servers through a single HTTP server. +A centralized MCP (Model Context Protocol) proxy server configuration for managing multiple MCP servers through a single interface. This setup simplifies Claude Desktop configuration by aggregating all MCP servers behind one proxy. -## Features +## ๐ŸŽฏ Purpose -- **Proxy Multiple MCP Clients**: Connects to multiple MCP resource servers and aggregates their tools and capabilities. -- **SSE Support**: Provides an SSE (Server-Sent Events) server for real-time updates. -- **Flexible Configuration**: Supports multiple client types (`stdio`, `sse` or `streamable-http`) with customizable settings. +Instead of managing 15+ individual MCP server connections in Claude Desktop, this proxy allows you to: +- Connect to **one proxy server** that handles everything +- Centralize configuration and logging +- Implement security controls and tool filtering +- Easily add/remove MCP servers without changing Claude config -## Installation +## ๐Ÿ—๏ธ Architecture -### Build from Source +``` +Claude Desktop โ†’ MCP Proxy โ†’ Your Individual MCP Servers + โ†“ + [brave-search, github, filesystem, puppeteer, + memory, sequential-thinking, git, browser-tools, etc.] +``` + +## ๐Ÿš€ Quick Start + +### 1. Prerequisites + +- Go 1.19+ (for building the proxy) +- Node.js and npm (for most MCP servers) +- uv/uvx (for Python-based MCP servers) + +### 2. Clone and Build - ```bash -git clone https://github.com/TBXark/mcp-proxy.git -cd mcp-proxy +```bash +git clone https://github.com/jlwainwright/mcp-proxy-setup.git +cd mcp-proxy-setup make build -./build/mcp-proxy --config path/to/config.json ``` -### Install by go +### 3. Configure ```bash -go install github.com/TBXark/mcp-proxy@latest -```` +# Copy example configuration +cp proxy-config.example.json proxy-config.json +cp claude-config.example.json claude-config.json + +# Edit proxy-config.json with your actual: +# - API keys +# - File paths +# - Environment variables +``` + +### 4. Update Claude Desktop -### Docker +Replace your Claude Desktop configuration: -> The Docker image supports two MCP calling methods by default: `npx` and `uvx`. ```bash -docker run -d -p 9090:9090 -v /path/to/config.json:/config/config.json ghcr.io/tbxark/mcp-proxy:latest -# or -docker run -d -p 9090:9090 ghcr.io/tbxark/mcp-proxy:latest --config https://example.com/path/to/config.json +# Backup current config +cp "~/Library/Application Support/Claude/claude_desktop_config.json" \ + "~/Library/Application Support/Claude/claude_desktop_config.json.backup" + +# Update with proxy config (edit paths first!) +cp claude-config.json "~/Library/Application Support/Claude/claude_desktop_config.json" ``` -## Configuration +### 5. Start the Proxy -The server is configured using a JSON file. Below is an example configuration: -> This is the format for the new version's configuration. The old version's configuration will be automatically converted to the new format's configuration when it is loaded. +```bash +./start-proxy.sh +``` + +### 6. Restart Claude Desktop + +## ๐Ÿ“‹ Included MCP Servers + +This configuration includes popular MCP servers: + +| Server | Description | Tools | +|--------|-------------|-------| +| **brave-search** | Web search capabilities | Web search, local search | +| **github** | GitHub repository management | Repo operations, code search | +| **filesystem** | Safe file system access | File operations, directory listing | +| **puppeteer** | Browser automation | Screenshots, navigation, interaction | +| **memory** | Knowledge graph storage | Entity management, relations | +| **sequential-thinking** | Step-by-step reasoning | Structured thinking | +| **git** | Git repository operations | Status, commit, branch management | +| **iterm** | Terminal integration | Command execution | +| **obsidian** | Note management | Vault operations | +| **browser-tools** | Browser dev tools | Debugging, auditing | -> You can use [`https://tbxark.github.io/mcp-proxy`](https://tbxark.github.io/mcp-proxy) to convert the configuration of `mcp-proxy` into the configuration that `Claude` can use. +## ๐Ÿ”ง Configuration -```jsonc +### Proxy Settings (`proxy-config.json`) + +```json { "mcpProxy": { - "baseURL": "https://mcp.example.com", + "baseURL": "http://localhost:9090", "addr": ":9090", "name": "MCP Proxy", - "version": "1.0.0", "options": { - "panicIfInvalid": false, "logEnabled": true, - "authTokens": [ - "DefaultTokens" - ] + "authTokens": ["your-auth-token"] } }, "mcpServers": { - "github": { + "server-name": { "command": "npx", - "args": [ - "-y", - "@modelcontextprotocol/server-github" - ], + "args": ["-y", "package-name"], "env": { - "GITHUB_PERSONAL_ACCESS_TOKEN": "" + "API_KEY": "your-api-key" }, "options": { "toolFilter": { - "mode": "block", - "list": [ - "create_or_update_file" - ] + "mode": "allow", + "list": ["tool1", "tool2"] } } - }, - "fetch": { - "command": "uvx", - "args": [ - "mcp-server-fetch" - ], - "options": { - "panicIfInvalid": true, - "logEnabled": false, - "authTokens": [ - "SpecificTokens" - ] - } - }, - "amap": { - "url": "https://mcp.amap.com/sse?key=" } } } ``` -### **`options`** -Common options for `mcpProxy` and `mcpServers`. +### Claude Desktop Config (`claude-config.json`) + +```json +{ + "mcpServers": { + "mcp-proxy": { + "command": "/path/to/mcp-proxy/build/mcp-proxy", + "args": ["--config", "/path/to/proxy-config.json"] + } + } +} +``` + +## ๐Ÿ”’ Security Features -- `panicIfInvalid`: If true, the server will panic if the client is invalid. -- `logEnabled`: If true, the server will log the client's requests. -- `authTokens`: A list of authentication tokens for the client. The `Authorization` header will be checked against this list. -- `toolFilter`: Optional tool filtering configuration. **This configuration is only effective in `mcpServers`.** - - `mode`: Specifies the filtering mode. Must be explicitly set to `allow` or `block` if `list` is provided. If `list` is present but `mode` is missing or invalid, the filter will be ignored for this server. - - `list`: A list of tool names to filter (either allow or block based on the `mode`). - > **Tip:** If you don't know the exact tool names, run the proxy once without any `toolFilter` configured. The console will log messages like ` Adding tool ` for each successfully registered tool. You can use these logged names in your `toolFilter` list. +- **Tool Filtering**: Each server has explicit allow-lists +- **Authentication**: Auth tokens for proxy access +- **Path Restrictions**: Filesystem access limited to safe directories +- **Environment Isolation**: Each MCP server runs separately -> In the new configuration, the `authTokens` of `mcpProxy` is not a global authentication token, but rather the default authentication token for `mcpProxy`. When `authTokens` is set in `mcpServers`, the value of `authTokens` in `mcpServers` will be used instead of the value in `mcpProxy`. In other words, the `authTokens` of `mcpProxy` serves as a default value and is only applied when `authTokens` is not set in `mcpServers`. +## ๐Ÿ› ๏ธ Management -> Other fields are the same. +### Adding New Servers -### **`mcpProxy`** -Proxy HTTP server configuration -- `baseURL`: The public accessible URL of the server. This is used to generate the URLs for the clients. -- `addr`: The address the server listens on. -- `name`: The name of the server. -- `version`: The version of the server. -- `options`: Default options for the `mcpServers`. +1. Add to `proxy-config.json`: +```json +"new-server": { + "command": "npx", + "args": ["-y", "new-mcp-package"], + "options": { + "toolFilter": { + "mode": "allow", + "list": ["allowed-tool"] + } + } +} +``` -### **`mcpServers`** -MCP server configuration, Adopt the same configuration format as other MCP Clients. -- `transportType`: The transport type of the MCP client. Except for `streamable-http`, which requires manual configuration, the rest will be automatically configured according to the content of the configuration file. - - `stdio`: The MCP client is a command line tool that is run in a subprocess. - - `sse`: The MCP client is a server that supports SSE (Server-Sent Events). - - `streamable-http`: The MCP client is a server that supports HTTP streaming. +2. Restart the proxy -For stdio mcp servers, the `command` field is required. -- `command`: The command to run the MCP client. -- `args`: The arguments to pass to the command. -- `env`: The environment variables to set for the command. -- `options`: Options specific to the client. +### Removing Servers -For sse mcp servers, the `url` field is required. When the current `url` exists, `sse` will be automatically configured. -- `url`: The URL of the MCP client. -- `headers`: The headers to send with the request to the MCP client. +1. Delete the server entry from `proxy-config.json` +2. Restart the proxy -For http streaming mcp servers, the `url` field is required. and `transportType` need to manually set to `streamable-http`. -- `url`: The URL of the MCP client. -- `headers`: The headers to send with the request to the MCP client. -- `timeout`: The timeout for the request to the MCP client. +### Viewing Logs +The proxy provides detailed logs showing: +- Server connection status +- Tool registrations +- Request routing +- Error details -## Usage +## ๐Ÿšจ Troubleshooting -``` -Usage of mcp-proxy: - -config string - path to config file or a http(s) url (default "config.json") - -help - print help and exit - -version - print version and exit -``` -1. The server will start and aggregate the tools and capabilities of the configured MCP clients. -2. You can access the server at `http(s)://{baseURL}/{clientName}/sse`. (e.g., `https://mcp.example.com/fetch/sse`, based on the example configuration) -3. If your MCP client does not support custom request headers., you can change the key in `clients` such as `fetch` to `fetch/{authToken}`, and then access it via `fetch/{authToken}`. +### Common Issues + +**Proxy won't start** +- Check if port 9090 is available: `lsof -i :9090` +- Verify all MCP packages are installed +- Check file paths in configuration + +**Claude can't connect** +- Ensure proxy is running +- Verify claude-config.json paths are correct +- Restart Claude Desktop after config changes + +**Missing tools** +- Check proxy logs for "Adding tool" messages +- Verify tool names in filter lists match exactly +- Ensure API keys are valid + +## ๐Ÿ“š Resources + +- [Model Context Protocol Specification](https://modelcontextprotocol.io/) +- [Official MCP Servers](https://github.com/modelcontextprotocol/servers) +- [TBXark MCP Proxy](https://github.com/TBXark/mcp-proxy) (base proxy) + +## ๐Ÿค Contributing + +1. Fork the repository +2. Create a feature branch +3. Make your changes +4. Test with your setup +5. Submit a pull request + +## ๐Ÿ“ License + +This project follows the MIT License. See individual MCP server licenses for their terms. -## Thanks +## ๐Ÿ™ Acknowledgments -- This project was inspired by the [adamwattis/mcp-proxy-server](https://github.com/adamwattis/mcp-proxy-server) project -- If you have any questions about deployment, you can refer to [ใ€Šๅœจ Docker ๆฒ™็ฎฑไธญ่ฟ่กŒ MCP Serverใ€‹](https://miantiao.me/posts/guide-to-running-mcp-server-in-a-sandbox/)([@ccbikai](https://github.com/ccbikai)) +- [TBXark](https://github.com/TBXark) for the excellent mcp-proxy implementation +- [Anthropic](https://github.com/anthropic) for Claude and MCP specification +- The MCP community for creating amazing servers -## License +--- -This project is licensed under the MIT License. See the [LICENSE](LICENSE) file for details. \ No newline at end of file +**Need help?** Open an issue or check the troubleshooting section above. diff --git a/claude-config.example.json b/claude-config.example.json new file mode 100644 index 0000000..e03daf6 --- /dev/null +++ b/claude-config.example.json @@ -0,0 +1,12 @@ +{ + "mcpServers": { + "mcp-proxy": { + "command": "/path/to/mcp-proxy/build/mcp-proxy", + "args": [ + "--config", + "/path/to/mcp-proxy/proxy-config.json" + ], + "env": {} + } + } +} diff --git a/proxy-config.example.json b/proxy-config.example.json new file mode 100644 index 0000000..83fead6 --- /dev/null +++ b/proxy-config.example.json @@ -0,0 +1,197 @@ +{ + "mcpProxy": { + "baseURL": "http://localhost:9090", + "addr": ":9090", + "name": "MCP Proxy", + "version": "1.0.0", + "options": { + "panicIfInvalid": false, + "logEnabled": true, + "authTokens": [ + "your-auth-token-here" + ] + } + }, + "mcpServers": { + "brave-search": { + "command": "npx", + "args": [ + "-y", + "@modelcontextprotocol/server-brave-search", + "--log-level=debug" + ], + "env": { + "BRAVE_API_KEY": "YOUR_BRAVE_API_KEY" + } + }, + "github": { + "command": "npx", + "args": [ + "-y", + "@modelcontextprotocol/server-github", + "--log-level=debug" + ], + "env": { + "GITHUB_PERSONAL_ACCESS_TOKEN": "YOUR_GITHUB_TOKEN" + }, + "options": { + "toolFilter": { + "mode": "allow", + "list": [ + "search_repositories", + "create_repository", + "get_file_contents", + "push_files", + "list_commits", + "list_issues", + "search_code" + ] + } + } + }, + "filesystem": { + "command": "npx", + "args": [ + "-y", + "@modelcontextprotocol/server-filesystem", + "/Users/username/Desktop", + "/Users/username/Downloads", + "/Users/username/DevFolder" + ], + "options": { + "toolFilter": { + "mode": "allow", + "list": [ + "read_file", + "read_multiple_files", + "list_directory", + "directory_tree", + "search_files", + "get_file_info" + ] + } + } + }, + "puppeteer": { + "command": "npx", + "args": [ + "-y", + "@modelcontextprotocol/server-puppeteer", + "--log-level=debug" + ], + "options": { + "toolFilter": { + "mode": "allow", + "list": [ + "puppeteer_screenshot", + "puppeteer_navigate", + "puppeteer_click", + "puppeteer_fill", + "puppeteer_select", + "puppeteer_hover", + "puppeteer_evaluate" + ] + } + } + }, + "memory": { + "command": "npx", + "args": [ + "-y", + "@modelcontextprotocol/server-memory" + ], + "options": { + "toolFilter": { + "mode": "allow", + "list": [ + "create_entities", + "create_relations", + "add_observations", + "delete_entities", + "delete_observations", + "delete_relations", + "search_nodes", + "read_graph", + "open_nodes" + ] + } + } + }, + "sequential-thinking": { + "command": "npx", + "args": [ + "-y", + "@modelcontextprotocol/server-sequential-thinking" + ] + }, + "git": { + "command": "uvx", + "args": [ + "mcp-server-git" + ], + "env": { + "REPO_PATH": "/path/to/your/repo" + }, + "options": { + "toolFilter": { + "mode": "allow", + "list": [ + "git_status", + "git_commit", + "git_reset", + "git_create_branch", + "git_checkout", + "git_show", + "git_diff", + "git_add", + "git_log" + ] + } + } + }, + "iterm": { + "command": "npx", + "args": [ + "-y", + "iterm-mcp" + ] + }, + "obsidian": { + "command": "npx", + "args": [ + "-y", + "@modelcontextprotocol/server-obsidian" + ], + "env": { + "VAULT_PATH": "/path/to/your/obsidian/vault" + } + }, + "browser-tools": { + "command": "npx", + "args": [ + "@agentdeskai/browser-tools-mcp@latest" + ], + "options": { + "toolFilter": { + "mode": "allow", + "list": [ + "getConsoleLogs", + "getConsoleErrors", + "getNetworkErrors", + "getNetworkLogs", + "takeScreenshot", + "getSelectedElement", + "runBestPracticesAudit", + "runAuditMode", + "runDebuggerMode", + "runNextJSAudit", + "runSEOAudit", + "runPerformanceAudit", + "runAccessibilityAudit", + "wipeLogs" + ] + } + } + } + } +} diff --git a/start-proxy.sh b/start-proxy.sh new file mode 100755 index 0000000..7e2293e --- /dev/null +++ b/start-proxy.sh @@ -0,0 +1,16 @@ +#!/bin/bash + +# MCP Proxy Startup Script +# This script starts the MCP Proxy server with your configuration + +cd /Users/jacques/DevFolder/mcp-proxy + +echo "๐Ÿš€ Starting MCP Proxy Server..." +echo "Configuration: proxy-config.json" +echo "Listening on: http://localhost:9090" +echo "" + +# Start the proxy server +./build/mcp-proxy --config proxy-config.json + +echo "โœ… MCP Proxy Server stopped" From 464cf481c56d097d49ee1efc222ec10477bae580 Mon Sep 17 00:00:00 2001 From: Jacques Wainwright Date: Sun, 25 May 2025 09:32:34 +0200 Subject: [PATCH 2/4] feat: Add comprehensive configuration examples and documentation - Add examples directory with multiple configuration patterns - Include simple and comprehensive example configurations - Add Claude Desktop integration configuration example - Provide detailed documentation for all configuration options - Add startup script for easy testing of different configurations - Document security best practices and tool filtering - Include common MCP server installation and setup instructions This addition helps new users get started quickly while providing advanced configuration patterns for power users. --- examples/README.md | 215 ++++++++++++++++++++ examples/configs/claude-desktop-config.json | 12 ++ examples/configs/comprehensive-example.json | 154 ++++++++++++++ examples/configs/simple-example.json | 28 +++ examples/start-example.sh | 124 +++++++++++ 5 files changed, 533 insertions(+) create mode 100644 examples/README.md create mode 100644 examples/configs/claude-desktop-config.json create mode 100644 examples/configs/comprehensive-example.json create mode 100644 examples/configs/simple-example.json create mode 100755 examples/start-example.sh diff --git a/examples/README.md b/examples/README.md new file mode 100644 index 0000000..ebec7b4 --- /dev/null +++ b/examples/README.md @@ -0,0 +1,215 @@ +# MCP Proxy Configuration Examples + +This directory contains various configuration examples to help you get started with MCP Proxy. Each example demonstrates different use cases and configuration patterns. + +## ๐Ÿ“ Configuration Files + +### 1. `simple-example.json` +A minimal configuration to get started quickly with just two MCP servers. + +**Use case**: First-time users who want to test the proxy with basic functionality. + +**Included servers**: +- Memory server (knowledge graph) +- Filesystem server (safe file access) + +### 2. `comprehensive-example.json` +A complete configuration showcasing all major MCP server types and features. + +**Use case**: Power users who want to see all available options and configuration patterns. + +**Included servers**: +- Brave Search (web search) +- GitHub (repository management) +- Filesystem (file operations) +- Memory (knowledge graph) +- Puppeteer (browser automation) +- Git (repository operations) +- Sequential Thinking (reasoning) +- Remote SSE server example +- Streamable HTTP server example + +**Features demonstrated**: +- Tool filtering with allow/block lists +- Environment variable configuration +- Authentication tokens +- Remote server connections +- Multiple transport types + +### 3. `claude-desktop-config.json` +Configuration file for Claude Desktop to connect to the MCP Proxy. + +**Use case**: Replace your complex Claude Desktop configuration with a single proxy connection. + +## ๐Ÿš€ Quick Start + +1. **Choose a configuration** that matches your needs +2. **Copy and customize** the configuration file: + ```bash + cp examples/configs/simple-example.json config.json + ``` +3. **Update the configuration** with your actual: + - API keys and tokens + - File paths + - Server URLs +4. **Start the proxy**: + ```bash + ./build/mcp-proxy --config config.json + ``` + +## ๐Ÿ”ง Configuration Guide + +### Basic Structure + +Every MCP Proxy configuration has two main sections: + +```json +{ + "mcpProxy": { + // Proxy server settings + }, + "mcpServers": { + // Individual MCP servers to proxy + } +} +``` + +### Proxy Settings (`mcpProxy`) + +| Field | Description | Required | +|-------|-------------|----------| +| `baseURL` | Public URL of the proxy server | Yes | +| `addr` | Address to listen on (e.g., `:9090`) | Yes | +| `name` | Display name for the proxy | No | +| `version` | Version identifier | No | +| `options.logEnabled` | Enable detailed logging | No | +| `options.authTokens` | Array of valid auth tokens | No | + +### Server Configuration (`mcpServers`) + +Each server in `mcpServers` can be configured as: + +#### Stdio Servers (Command-line) +```json +"server-name": { + "command": "npx", + "args": ["-y", "package-name"], + "env": { + "API_KEY": "your-key" + } +} +``` + +#### SSE Servers (Remote) +```json +"server-name": { + "url": "https://server.com/sse", + "headers": { + "Authorization": "Bearer token" + } +} +``` + +#### Streamable HTTP Servers +```json +"server-name": { + "transportType": "streamable-http", + "url": "https://server.com/mcp", + "timeout": 30 +} +``` + +### Tool Filtering + +Control which tools are available from each server: + +```json +"options": { + "toolFilter": { + "mode": "allow", // or "block" + "list": ["tool1", "tool2", "tool3"] + } +} +``` + +**Modes**: +- `allow`: Only listed tools are available +- `block`: Listed tools are blocked, others are available + +## ๐Ÿ”’ Security Best Practices + +1. **Use tool filtering** to limit available functionality +2. **Set authentication tokens** for proxy access +3. **Limit filesystem paths** to safe directories only +4. **Use environment variables** for sensitive data +5. **Review server permissions** regularly + +## ๐Ÿ› ๏ธ Environment Variables + +For security, use environment variables for sensitive data: + +```bash +export GITHUB_TOKEN="your-token" +export BRAVE_API_KEY="your-key" +``` + +Then reference in config: +```json +"env": { + "GITHUB_PERSONAL_ACCESS_TOKEN": "${GITHUB_TOKEN}" +} +``` + +## ๐Ÿ“‹ Common Server Examples + +### Popular MCP Servers + +| Server | Package | Description | +|--------|---------|-------------| +| **Memory** | `@modelcontextprotocol/server-memory` | Knowledge graph storage | +| **Filesystem** | `@modelcontextprotocol/server-filesystem` | File operations | +| **GitHub** | `@modelcontextprotocol/server-github` | Repository management | +| **Brave Search** | `@modelcontextprotocol/server-brave-search` | Web search | +| **Puppeteer** | `@modelcontextprotocol/server-puppeteer` | Browser automation | +| **Git** | `mcp-server-git` (via uvx) | Git operations | + +### Installation Commands + +```bash +# Install common MCP servers +npm install -g @modelcontextprotocol/server-memory +npm install -g @modelcontextprotocol/server-filesystem +npm install -g @modelcontextprotocol/server-github +npm install -g @modelcontextprotocol/server-brave-search +npm install -g @modelcontextprotocol/server-puppeteer + +# Install Python-based servers +pip install mcp-server-git +``` + +## ๐Ÿ” Debugging + +1. **Enable logging** in proxy configuration: + ```json + "options": { + "logEnabled": true + } + ``` + +2. **Check server connections** in logs +3. **Verify tool registration** messages +4. **Test individual servers** before adding to proxy + +## ๐Ÿค Contributing + +Found a useful configuration pattern? Please contribute! + +1. Add your example to `examples/configs/` +2. Update this README with documentation +3. Submit a pull request + +## ๐Ÿ“š Additional Resources + +- [MCP Specification](https://modelcontextprotocol.io/) +- [Official MCP Servers](https://github.com/modelcontextprotocol/servers) +- [Claude Desktop Integration](https://docs.anthropic.com/claude/docs) diff --git a/examples/configs/claude-desktop-config.json b/examples/configs/claude-desktop-config.json new file mode 100644 index 0000000..8e82d33 --- /dev/null +++ b/examples/configs/claude-desktop-config.json @@ -0,0 +1,12 @@ +{ + "mcpServers": { + "mcp-proxy": { + "command": "/path/to/mcp-proxy/build/mcp-proxy", + "args": [ + "--config", + "/path/to/mcp-proxy/config.json" + ], + "env": {} + } + } +} diff --git a/examples/configs/comprehensive-example.json b/examples/configs/comprehensive-example.json new file mode 100644 index 0000000..a449b93 --- /dev/null +++ b/examples/configs/comprehensive-example.json @@ -0,0 +1,154 @@ +{ + "mcpProxy": { + "baseURL": "http://localhost:9090", + "addr": ":9090", + "name": "MCP Proxy Server", + "version": "1.0.0", + "options": { + "panicIfInvalid": false, + "logEnabled": true, + "authTokens": [ + "your-auth-token-here" + ] + } + }, + "mcpServers": { + "brave-search": { + "command": "npx", + "args": [ + "-y", + "@modelcontextprotocol/server-brave-search" + ], + "env": { + "BRAVE_API_KEY": "YOUR_BRAVE_API_KEY" + }, + "options": { + "logEnabled": true + } + }, + "github": { + "command": "npx", + "args": [ + "-y", + "@modelcontextprotocol/server-github" + ], + "env": { + "GITHUB_PERSONAL_ACCESS_TOKEN": "YOUR_GITHUB_TOKEN" + }, + "options": { + "toolFilter": { + "mode": "allow", + "list": [ + "search_repositories", + "create_repository", + "get_file_contents", + "push_files", + "list_commits", + "list_issues", + "search_code" + ] + } + } + }, + "filesystem": { + "command": "npx", + "args": [ + "-y", + "@modelcontextprotocol/server-filesystem", + "/path/to/safe/directory1", + "/path/to/safe/directory2" + ], + "options": { + "toolFilter": { + "mode": "allow", + "list": [ + "read_file", + "read_multiple_files", + "list_directory", + "directory_tree", + "search_files", + "get_file_info" + ] + } + } + }, + "memory": { + "command": "npx", + "args": [ + "-y", + "@modelcontextprotocol/server-memory" + ], + "options": { + "toolFilter": { + "mode": "allow", + "list": [ + "create_entities", + "create_relations", + "add_observations", + "search_nodes", + "read_graph" + ] + } + } + }, + "puppeteer": { + "command": "npx", + "args": [ + "-y", + "@modelcontextprotocol/server-puppeteer" + ], + "options": { + "toolFilter": { + "mode": "allow", + "list": [ + "puppeteer_screenshot", + "puppeteer_navigate", + "puppeteer_click", + "puppeteer_fill" + ] + } + } + }, + "git": { + "command": "uvx", + "args": [ + "mcp-server-git" + ], + "env": { + "REPO_PATH": "/path/to/your/git/repository" + }, + "options": { + "toolFilter": { + "mode": "allow", + "list": [ + "git_status", + "git_log", + "git_show", + "git_diff" + ] + } + } + }, + "sequential-thinking": { + "command": "npx", + "args": [ + "-y", + "@modelcontextprotocol/server-sequential-thinking" + ] + }, + "remote-sse-server": { + "url": "https://your-remote-server.com/sse", + "headers": { + "Authorization": "Bearer YOUR_TOKEN" + } + }, + "streamable-http-server": { + "transportType": "streamable-http", + "url": "https://your-streamable-server.com/mcp", + "headers": { + "Authorization": "Bearer YOUR_TOKEN" + }, + "timeout": 30 + } + } +} diff --git a/examples/configs/simple-example.json b/examples/configs/simple-example.json new file mode 100644 index 0000000..900a506 --- /dev/null +++ b/examples/configs/simple-example.json @@ -0,0 +1,28 @@ +{ + "mcpProxy": { + "baseURL": "http://localhost:9090", + "addr": ":9090", + "name": "Simple MCP Proxy", + "version": "1.0.0", + "options": { + "logEnabled": true + } + }, + "mcpServers": { + "memory": { + "command": "npx", + "args": [ + "-y", + "@modelcontextprotocol/server-memory" + ] + }, + "filesystem": { + "command": "npx", + "args": [ + "-y", + "@modelcontextprotocol/server-filesystem", + "/Users/username/Documents" + ] + } + } +} diff --git a/examples/start-example.sh b/examples/start-example.sh new file mode 100755 index 0000000..b657a15 --- /dev/null +++ b/examples/start-example.sh @@ -0,0 +1,124 @@ +#!/bin/bash + +# MCP Proxy Example Launcher +# This script helps you quickly start the proxy with different example configurations + +set -e + +# Colors for output +RED='\033[0;31m' +GREEN='\033[0;32m' +YELLOW='\033[1;33m' +BLUE='\033[0;34m' +NC='\033[0m' # No Color + +# Configuration directory +EXAMPLES_DIR="$(dirname "$0")/configs" +BUILD_DIR="$(dirname "$0")/../build" +PROXY_BINARY="$BUILD_DIR/mcp-proxy" + +# Function to print colored output +print_color() { + printf "${1}${2}${NC}\n" +} + +# Function to show usage +show_usage() { + echo "Usage: $0 [config-name]" + echo "" + echo "Available configurations:" + echo " simple - Simple two-server setup (memory + filesystem)" + echo " comprehensive - Complete setup with all server types" + echo " custom - Use your own config.json file" + echo "" + echo "Examples:" + echo " $0 simple # Start with simple configuration" + echo " $0 comprehensive # Start with comprehensive configuration" + echo " $0 custom # Start with ./config.json" + echo "" +} + +# Function to check if binary exists +check_binary() { + if [ ! -f "$PROXY_BINARY" ]; then + print_color $RED "โŒ MCP Proxy binary not found at: $PROXY_BINARY" + print_color $YELLOW "Please build the proxy first:" + print_color $BLUE " make build" + exit 1 + fi +} + +# Function to validate config +validate_config() { + local config_file="$1" + + if [ ! -f "$config_file" ]; then + print_color $RED "โŒ Configuration file not found: $config_file" + exit 1 + fi + + # Basic JSON validation + if ! python3 -m json.tool "$config_file" >/dev/null 2>&1; then + print_color $RED "โŒ Invalid JSON in configuration file: $config_file" + exit 1 + fi + + print_color $GREEN "โœ… Configuration file is valid" +} + +# Function to start proxy +start_proxy() { + local config_file="$1" + local config_name="$2" + + print_color $BLUE "๐Ÿš€ Starting MCP Proxy with $config_name configuration..." + print_color $YELLOW "Configuration: $config_file" + print_color $YELLOW "Proxy URL: http://localhost:9090" + print_color $YELLOW "" + print_color $YELLOW "Press Ctrl+C to stop the proxy" + print_color $YELLOW "" + + exec "$PROXY_BINARY" --config "$config_file" +} + +# Main script +main() { + local config_name="${1:-}" + + # Show usage if no arguments or help requested + if [ -z "$config_name" ] || [ "$config_name" = "-h" ] || [ "$config_name" = "--help" ]; then + show_usage + exit 0 + fi + + # Check if binary exists + check_binary + + # Determine config file + case "$config_name" in + "simple") + config_file="$EXAMPLES_DIR/simple-example.json" + display_name="Simple" + ;; + "comprehensive") + config_file="$EXAMPLES_DIR/comprehensive-example.json" + display_name="Comprehensive" + ;; + "custom") + config_file="./config.json" + display_name="Custom" + ;; + *) + print_color $RED "โŒ Unknown configuration: $config_name" + show_usage + exit 1 + ;; + esac + + # Validate and start + validate_config "$config_file" + start_proxy "$config_file" "$display_name" +} + +# Run main function with all arguments +main "$@" From 95dc109845e5d9d0cb1aaf1056ad011de74dd5e6 Mon Sep 17 00:00:00 2001 From: Jacques Wainwright Date: Sun, 25 May 2025 09:40:59 +0200 Subject: [PATCH 3/4] security: Add local config files to gitignore --- .gitignore | 2 ++ 1 file changed, 2 insertions(+) diff --git a/.gitignore b/.gitignore index 4ec9b54..25a0641 100644 --- a/.gitignore +++ b/.gitignore @@ -46,3 +46,5 @@ vendor/ # Uncomment these if you want to exclude configs with API keys # proxy-config.json # claude-config.json +proxy-config.json +claude-config.json From 860373b37df75643ea68956664b9c8411e071b21 Mon Sep 17 00:00:00 2001 From: Jacques Wainwright Date: Sun, 25 May 2025 09:56:25 +0200 Subject: [PATCH 4/4] fix: Address code review feedback from Gemini Code Assist - Remove user-specific files (README-SETUP.md, start-proxy.sh) - Use generic path placeholders instead of OS-specific paths - Add multi-platform support for Claude Desktop config paths - Clarify Python package installation methods (uv vs pip) - Remove hardcoded paths to improve portability Fixes all critical, high, and medium severity issues identified in the automated code review. --- README-SETUP.md | 167 -------------------- README.md | 13 +- examples/README.md | 6 +- examples/configs/claude-desktop-config.json | 4 +- examples/configs/simple-example.json | 2 +- start-proxy.sh | 16 -- 6 files changed, 20 insertions(+), 188 deletions(-) delete mode 100644 README-SETUP.md delete mode 100755 start-proxy.sh diff --git a/README-SETUP.md b/README-SETUP.md deleted file mode 100644 index 672ab75..0000000 --- a/README-SETUP.md +++ /dev/null @@ -1,167 +0,0 @@ -# Jacques' MCP Proxy Setup - -## ๐ŸŽฏ What This Is - -This MCP (Model Context Protocol) proxy centralizes **all your MCP servers** into a single interface that Claude can connect to. Instead of managing 15+ individual MCP server connections, Claude now only needs to connect to **one proxy server** that handles everything. - -## ๐Ÿ—๏ธ Architecture - -``` -Claude Desktop โ†’ MCP Proxy โ†’ Your Individual MCP Servers - โ†“ - [brave-search, github, filesystem, puppeteer, - memory, sequential-thinking, git, iterm, - n8n, obsidian, whatsapp, browser-tools] -``` - -## ๐Ÿ“ Files Created - -- `proxy-config.json` - Configuration for all your MCP servers -- `claude-config.json` - Simplified Claude Desktop configuration -- `start-proxy.sh` - Easy startup script -- `build/mcp-proxy` - The compiled proxy server binary - -## ๐Ÿš€ Quick Start - -### 1. Start the Proxy Server -```bash -cd /Users/jacques/DevFolder/mcp-proxy -./start-proxy.sh -``` - -### 2. Update Claude Desktop Configuration - -Replace your current `claude_desktop_config.json` with the contents of `claude-config.json`: - -**Location**: `~/Library/Application Support/Claude/claude_desktop_config.json` - -```bash -# Backup your current config -cp "~/Library/Application Support/Claude/claude_desktop_config.json" "~/Library/Application Support/Claude/claude_desktop_config.json.backup" - -# Copy the new simplified config -cp "/Users/jacques/DevFolder/mcp-proxy/claude-config.json" "~/Library/Application Support/Claude/claude_desktop_config.json" -``` - -### 3. Restart Claude Desktop - -## ๐Ÿ”ง Configuration Details - -### Proxy Settings -- **URL**: http://localhost:9090 -- **Auth Token**: `mcp-proxy-token-2025` -- **Tool Filtering**: Enabled with allow-lists for security - -### Included MCP Servers -- **brave-search**: Web search capabilities -- **github**: GitHub repository management -- **filesystem**: File system access with safe paths -- **puppeteer**: Browser automation -- **memory**: Knowledge graph and memory -- **sequential-thinking**: Step-by-step reasoning -- **git**: Git repository operations -- **iterm**: Terminal integration -- **n8n**: Workflow automation -- **obsidian**: Note management -- **whatsapp**: WhatsApp integration -- **browser-tools**: Browser development tools - -## ๐Ÿ”’ Security Features - -- **Tool Filtering**: Each server has explicit allow-lists of permitted tools -- **Authentication**: Uses auth tokens for proxy access -- **Safe Paths**: Filesystem access restricted to approved directories only -- **Environment Isolation**: Each MCP server runs in its own process - -## ๐Ÿ› ๏ธ Management Commands - -### Start Proxy -```bash -cd /Users/jacques/DevFolder/mcp-proxy -./start-proxy.sh -``` - -### Stop Proxy -Press `Ctrl+C` in the terminal running the proxy - -### Check Status -Visit: http://localhost:9090/health (if health endpoint exists) - -### View Logs -The proxy outputs detailed logs showing: -- Server connections -- Tool registrations -- Request routing -- Error debugging - -## ๐Ÿ”ง Customization - -### Adding New MCP Servers -Edit `proxy-config.json` and add to the `mcpServers` section: - -```json -"your-new-server": { - "command": "npx", - "args": ["-y", "your-mcp-package"], - "env": { - "API_KEY": "your-api-key" - }, - "options": { - "toolFilter": { - "mode": "allow", - "list": ["tool1", "tool2"] - } - } -} -``` - -### Removing Servers -Simply delete the server entry from `proxy-config.json` - -### Updating Tool Filters -Modify the `toolFilter.list` arrays to add/remove allowed tools - -## ๐Ÿšจ Troubleshooting - -### Proxy Won't Start -- Check if port 9090 is available: `lsof -i :9090` -- Verify all MCP commands are installed (npx, uvx, etc.) -- Check file paths in configuration - -### Claude Can't Connect -- Ensure proxy is running: `./start-proxy.sh` -- Verify claude-config.json is in the right location -- Restart Claude Desktop after config changes - -### Individual Servers Failing -- Check the proxy logs for specific error messages -- Verify environment variables and API keys -- Test individual servers directly if needed - -### Missing Tools -- Check proxy logs for "Adding tool" messages -- Verify tool names in toolFilter lists match exactly -- Some servers may need additional setup or API keys - -## ๐ŸŽ‰ Benefits - -โœ… **Simplified Management**: One config file instead of 15+ -โœ… **Better Security**: Centralized tool filtering and access control -โœ… **Easier Debugging**: Single log output for all servers -โœ… **Performance**: Reduced Claude startup time -โœ… **Maintainability**: Easy to add/remove servers -โœ… **Reliability**: Failed servers don't break others - -## ๐Ÿ“ž Support - -If you need to modify this setup: -1. Edit `proxy-config.json` for server changes -2. Run `./start-proxy.sh` to restart -3. Check logs for any issues -4. Update tool filters as needed - ---- - -**Created**: May 25, 2025 -**Version**: 1.0 -**Proxy**: TBXark/mcp-proxy v1.0.0 diff --git a/README.md b/README.md index 9bbb2aa..fe5d6d7 100644 --- a/README.md +++ b/README.md @@ -52,6 +52,7 @@ cp claude-config.example.json claude-config.json Replace your Claude Desktop configuration: +**On macOS:** ```bash # Backup current config cp "~/Library/Application Support/Claude/claude_desktop_config.json" \ @@ -61,10 +62,20 @@ cp "~/Library/Application Support/Claude/claude_desktop_config.json" \ cp claude-config.json "~/Library/Application Support/Claude/claude_desktop_config.json" ``` +**On Windows:** +```bash +# Backup current config +cp "%APPDATA%/Claude/claude_desktop_config.json" \ + "%APPDATA%/Claude/claude_desktop_config.json.backup" + +# Update with proxy config (edit paths first!) +cp claude-config.json "%APPDATA%/Claude/claude_desktop_config.json" +``` + ### 5. Start the Proxy ```bash -./start-proxy.sh +./build/mcp-proxy --config config.json ``` ### 6. Restart Claude Desktop diff --git a/examples/README.md b/examples/README.md index ebec7b4..db5b685 100644 --- a/examples/README.md +++ b/examples/README.md @@ -183,7 +183,11 @@ npm install -g @modelcontextprotocol/server-github npm install -g @modelcontextprotocol/server-brave-search npm install -g @modelcontextprotocol/server-puppeteer -# Install Python-based servers +# Install Python-based servers (choose one method) +# Using uv (recommended): +uvx mcp-server-git + +# Or using pip: pip install mcp-server-git ``` diff --git a/examples/configs/claude-desktop-config.json b/examples/configs/claude-desktop-config.json index 8e82d33..b8b436b 100644 --- a/examples/configs/claude-desktop-config.json +++ b/examples/configs/claude-desktop-config.json @@ -1,10 +1,10 @@ { "mcpServers": { "mcp-proxy": { - "command": "/path/to/mcp-proxy/build/mcp-proxy", + "command": "/path/to/your/mcp-proxy/build/mcp-proxy", "args": [ "--config", - "/path/to/mcp-proxy/config.json" + "/path/to/your/mcp-proxy/config.json" ], "env": {} } diff --git a/examples/configs/simple-example.json b/examples/configs/simple-example.json index 900a506..0d3496d 100644 --- a/examples/configs/simple-example.json +++ b/examples/configs/simple-example.json @@ -21,7 +21,7 @@ "args": [ "-y", "@modelcontextprotocol/server-filesystem", - "/Users/username/Documents" + "/path/to/your/documents" ] } } diff --git a/start-proxy.sh b/start-proxy.sh deleted file mode 100755 index 7e2293e..0000000 --- a/start-proxy.sh +++ /dev/null @@ -1,16 +0,0 @@ -#!/bin/bash - -# MCP Proxy Startup Script -# This script starts the MCP Proxy server with your configuration - -cd /Users/jacques/DevFolder/mcp-proxy - -echo "๐Ÿš€ Starting MCP Proxy Server..." -echo "Configuration: proxy-config.json" -echo "Listening on: http://localhost:9090" -echo "" - -# Start the proxy server -./build/mcp-proxy --config proxy-config.json - -echo "โœ… MCP Proxy Server stopped"