MCP Router

Um gateway unificado para rotear requisições para múltiplos servidores do Model Context Protocol.

Documentação

MCP Anywhere

Um gateway unificado para servidores Model Context Protocol (MCP) que permite descoberta, configuração e acesso a ferramentas de repositórios GitHub por meio de um único endpoint.

https://github.com/user-attachments/assets/f011f8bf-6c99-4a8a-8236-f8eb0a3fb9e4

Versão Atual: 0.8.0
Nota: Este projeto está em beta. APIs e recursos estão sujeitos a alterações.

Visão Geral

O MCP Anywhere oferece:

Descoberta automática de ferramentas a partir de repositórios GitHub
Gerenciamento centralizado de chaves de API e credenciais
Ativação seletiva de ferramentas e controle de acesso
Endpoint unificado para todas as ferramentas MCP
Isolamento baseado em Docker para execução segura

Documentação

📚 Documentação completa disponível em mcpanywhere.com

Começando - Guia de início rápido e instalação
Guia de Implantação - Implante em produção com Fly.io

Instalação

Instalação Local

# Clone repository
git clone https://github.com/locomotive-agency/mcp-anywhere.git
cd mcp-anywhere

# Install with uv (recommended)
uv sync

# Or install with pip
pip install -e .

# Configure environment
cp env.example .env
# Edit .env with required values:
# SECRET_KEY=<secure-random-key>
# ANTHROPIC_API_KEY=<your-api-key>

# Start server
mcp-anywhere serve http
# Or: python -m mcp_anywhere serve http
# Access at http://localhost:8000

Implantação em Produção (Fly.io)

# Install Fly CLI
curl -L https://fly.io/install.sh | sh

# Deploy application
cd mcp-anywhere
fly launch
fly secrets set SECRET_KEY=<secure-random-key>
fly secrets set JWT_SECRET_KEY=<jwt-secret-key>
fly secrets set ANTHROPIC_API_KEY=<your-api-key>
fly secrets set GOOGLE_OAUTH_CLIENT_ID=<google-oauth-client-id>
fly secrets set GOOGLE_OAUTH_CLIENT_SECRET=<google-oauth-client-secret>
fly deploy

# Application available at https://your-app.fly.dev

Para acelerar a implantação no fly.io, você pode configurar a compilação manual e o início dos contêineres.

# set the environment variable
REBUILD_CONTAINERS_ON_STARTUP=false

Docker

Implantando o aplicativo como um contêiner docker usando docker compose.

# Configure environment
cp env.example .env
# Edit .env with required values:
# SECRET_KEY=<secure-random-key>
# ANTHROPIC_API_KEY=<your-api-key>

Compile e implante o aplicativo

$ docker compose -f docker-compose.native.yml up -d --build

Veja os logs para verificar o status

$ docker logs mcp-anywhere-app

Navegue até http://<DOCKER-HOST>:8000/ para usar o aplicativo

Interaja com a máquina via CLI, útil para interagir com o banco de dados usando sqlite3

# fetch machine id for your app
$ fly --app mcp-anywhere-app machine list

$ fly console --app mcp-anywhere-app --machine <MACHINE_ID>

Comandos de exemplo do banco de dados, após fazer login no console da máquina

$ sqlite3 /.data/mcp_anywhere.db ".tables"

$ sqlite3 /.data/mcp_anywhere.db "SELECT * FROM users;"

Uso

Adicionando Ferramentas do GitHub

Use a interface web para adicionar repositórios de servidores MCP:

Servidores MCP oficiais: https://github.com/modelcontextprotocol/servers
Interpretador Python: https://github.com/yzfly/mcp-python-interpreter
Qualquer repositório MCP compatível

O sistema usa Claude AI para analisar e configurar repositórios automaticamente.

Configuração

Chaves de API: Armazenamento centralizado de credenciais
Arquivos Secretos: Upload seguro e gerenciamento de arquivos de credenciais (JSON, PEM, certificados)
Gerenciamento de Ferramentas: Ative ou desative ferramentas específicas
Configurações do Contêiner: Contêinerização automática com Docker

Gerenciamento de Arquivos Secretos

O MCP Anywhere suporta upload seguro e gerenciamento de arquivos de credenciais para servidores MCP:

Tipos de Arquivo Suportados:

Arquivos de credenciais JSON (.json)
Certificados e chaves PEM (.pem, .key, .crt, .cert)
Certificados PKCS12/PFX (.p12, .pfx)
Java KeyStores (.jks, .keystore)
Arquivos de configuração (.yaml, .yml, .xml, .txt)

Recursos:

Os arquivos são criptografados em repouso usando AES-128 (Fernet)
Tamanho máximo do arquivo: 10MB
Os arquivos são montados como volumes somente leitura nos contêineres
Variáveis de ambiente definidas automaticamente com os caminhos dos arquivos
Limpeza automática quando os servidores são excluídos

Uso via Interface Web:

Navegue até a página de detalhes do servidor
Use o formulário "Enviar Arquivo Secreto"
Especifique um nome de variável de ambiente (por exemplo, GOOGLE_APPLICATION_CREDENTIALS)
Envie o arquivo de credenciais
O arquivo será montado automaticamente quando o contêiner iniciar

Considerações de Segurança:

Os arquivos são armazenados criptografados em DATA_DIR/secrets/<server_id>/
Cada servidor possui armazenamento de segredos isolado
Os arquivos são descriptografados apenas ao montar nos contêineres
O acesso ao contêiner é somente leitura

Integração com Clientes

Configuração do Claude Desktop:

Primeiro execute which uv, que imprimirá um caminho para o binário uv. Por exemplo, no macOS:

/Users/yourname/.local/bin/uv

Você pode então usar isso no comando de início. Altere o caminho --directory para o caminho do seu clone do MCP Anywhere.

{
  "mcpServers": {
    "mcp-anywhere": {
      "command": "/Users/yourname/.local/bin/uv",
      "args": ["run", "--directory", "/Users/yourname/Projects/mcp-anywhere", "mcp-anywhere", "connect"]
    }
  }
}

Por fim, configure o aplicativo MCP Anywhere antes de iniciar o Claude Desktop:

uv run mcp-anywhere serve stdio

Opções de Autenticação:

Para Google OAuth (recomendado para equipes):

Configure as credenciais do Google OAuth no Google Cloud Console

Configure as variáveis de ambiente:

GOOGLE_OAUTH_CLIENT_ID=your-client-id
GOOGLE_OAUTH_CLIENT_SECRET=your-client-secret
GOOGLE_OAUTH_REDIRECT_URI=/auth/callback
OAUTH_USER_ALLOWED_DOMAIN=company.com  # Optional: restrict to your domain

Os usuários podem entrar com o Google em /auth/login

Integração com API HTTP:

from fastmcp import Client
from fastmcp.client.auth import BearerAuth

async with Client(
    "https://your-app.fly.dev/mcp/",
    auth=BearerAuth(token="<oauth-token>")
) as client:
    tools = await client.list_tools()

Interface de Linha de Comando:

# For MCP client connection
mcp-anywhere connect
# Or: python -m mcp_anywhere connect

# For STDIO server mode (local Claude Desktop integration)
mcp-anywhere serve stdio

# For HTTP server mode with OAuth (production)
mcp-anywhere serve http --host 0.0.0.0 --port 8000

Recursos

Autenticação e Controle de Acesso

Integração com Google OAuth - Entre com o Google para autenticação simplificada
Controle de acesso baseado em domínio - Restrinja o acesso a usuários de domínios específicos (por exemplo, @empresa.com)
Autenticação web baseada em sessão com gerenciamento seguro de cookies
Tokens JWT para acesso à API com validação adequada de escopo

Descoberta e Gerenciamento de Ferramentas

Análise automática de repositórios usando Claude AI
Monitoramento de saúde do contêiner com remontagem inteligente
Suporte para runtimes npx, uvx e Docker
Ativação seletiva de ferramentas com controles por servidor
Gerenciamento aprimorado de servidores - Inicie, pare e reinicie servidores pela interface web
Interpretador Python pré-configurado com isolamento em sandbox

Segurança e Autenticação

Integração com Google OAuth para autenticação simplificada de usuários
Controle de acesso baseado em domínio para segurança organizacional
Suporte a OAuth 2.0/2.1 com PKCE (implementação do MCP SDK)
Autenticação de API baseada em JWT
Isolamento de contêiner Docker para execução de ferramentas
Autenticação baseada em sessão para interface web
Armazenamento criptografado de arquivos secretos (AES-128 com Fernet)

Arquitetura de Produção

Arquitetura assíncrona (Starlette/FastAPI)
Monitoramento de saúde com recuperação automática
Gerenciamento flexível de contêineres com comportamento configurável de início/parada
Gerenciamento aprimorado do ciclo de vida do servidor com controles de iniciar/parar/reiniciar
Processo de implantação simplificado com GitHub Actions CI
Suporte a CLI para acesso direto a ferramentas

Arquitetura

Client Application → MCP Anywhere Gateway → Docker Containers → MCP Tools
                            ↓
                    Web Management Interface

Contribuindo

Áreas para contribuição:

Revisão de OAuth e suporte a provedores adicionais
Eficiência e latência de contêineres
Melhorar testes
Documentação

Configuração

Variáveis de Ambiente Obrigatórias

SECRET_KEY                  # Session encryption key
ANTHROPIC_API_KEY          # Claude API key for repository analysis

Variáveis de Ambiente Opcionais

JWT_SECRET_KEY             # JWT token signing key (defaults to SECRET_KEY)
WEB_PORT                   # Web interface port (default: 8000)
DATA_DIR                   # Data storage directory (default: .data)
DOCKER_TIMEOUT             # Container operation timeout in seconds (default: 300)
LOG_LEVEL                  # Logging level (default: INFO)
GITHUB_TOKEN               # GitHub token for private repository access

# Container Management
CLEANUP_CONTAINERS_ON_SHUTDOWN    # Clean up containers on app shutdown (default: false)
REBUILD_CONTAINERS_ON_STARTUP     # Rebuild containers on startup (default: true)

# Google OAuth (optional - enables Google authentication)
GOOGLE_OAUTH_CLIENT_ID            # Google OAuth client ID
GOOGLE_OAUTH_CLIENT_SECRET        # Google OAuth client secret  
GOOGLE_OAUTH_REDIRECT_URI         # OAuth redirect URI (e.g., /auth/callback)
OAUTH_USER_ALLOWED_DOMAIN         # Restrict access to specific domain (e.g., company.com)

Desenvolvimento

Configuração de Desenvolvimento

# Install development dependencies
uv sync --group dev

# Run tests
uv run pytest

# Run linting
uv run ruff check src/ tests/

# Run type checking
uv run mypy src/

Testes

# Run all tests
uv run pytest

# Run tests with coverage
uv run pytest --cov=mcp_anywhere

uv run mcp-anywhere serve http --host 0.0.0.0 --port 8080

Modo de Depuração

LOG_LEVEL=DEBUG mcp-anywhere serve http

Redefinição de Dados

mcp-anywhere reset --confirm

Suporte

Licença

Veja LICENÇA