JinaAI

MCP leve do JINA AI

GitHub

Experimente este MCPPatrocinado

Documentação

THIS IS ARCHIVE Encontre um sucessor melhor: https://github.com/ciborro/webskim

Servidor MCP Jina

Servidor Model Context Protocol (MCP) para as APIs Reader e Search da Jina.AI.

Versão 1.0.0

Um servidor MCP leve e eficiente para APIs Jina.AI

✅ 9 ferramentas MCP totalmente testadas
✅ Suporte completo às APIs Reader e Search
✅ Opções avançadas de filtragem e extração
✅ Operações paralelas com tratamento de requisições concorrentes
✅ Tratamento abrangente de erros e registro de logs
✅ Redução de 50% no consumo de tokens em comparação a implementações alternativas
✅ Pronto para produção com documentação completa

Documentação

Início Rápido - Comece a usar em 5 minutos
Tratamento de Erros e Solução de Problemas - Problemas comuns e soluções

Visão Geral

Este servidor MCP fornece 9 ferramentas para interagir com as APIs Jina.AI:

Ferramentas da API Reader (5)

primer - Obter status do servidor e informações do sistema
read_url - Extrair conteúdo de uma URL
capture_screenshot_url - Capturar uma captura de tela de uma página web
guess_datetime_url - Detectar a data de publicação de uma URL
parallel_read_url - Ler múltiplas URLs simultaneamente

Ferramentas da API Search (4)

search_web - Realizar busca web com filtragem avançada
search_arxiv - Buscar artigos acadêmicos no ArXiv
search_images - Buscar imagens
parallel_search_web - Realizar múltiplas buscas web simultaneamente

Instalação e Início Rápido

Clonar e Instalar

# Clone the repository
git clone https://github.com/ciborro/jina-light-mcp.git
cd jina-mcp-server

# Install dependencies
npm install

# Build TypeScript
npm run build

# Install globally (optional)
npm install -g .

Verificar a Instalação

# Check if installed globally
which jina-mcp-server

# Start the server
npm start

Você deve ver:

[INFO] Jina MCP Server starting...
[INFO] Registered 9 tools
[OK] Jina MCP Server running on stdio transport

Para instruções detalhadas de configuração, consulte o Guia de Início Rápido.

Configuração

Definir Sua Chave de API

Crie um arquivo .env na raiz do projeto com sua chave de API Jina:

echo "JINA_API_KEY=your_api_key_here" > .env

Ou edite o arquivo .env diretamente:

JINA_API_KEY=jina_xxxxxxxxxxxxxxxxxxxxx

Você pode obter uma chave de API gratuita em https://jina.ai/api

Uso

Teste Local com o MCP Inspector

npm run dev

O servidor iniciará no transporte stdio. Em outro terminal, use mcp-cli ou o MCP Inspector para testar:

npx @modelcontextprotocol/inspector npx npm start

Isso abre uma interface web em http://localhost:5173 onde você pode testar cada ferramenta.

Integração com Claude Desktop (Local)

Adicione ao ~/Library/Application\ Support/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "jina-mcp-local": {
      "command": "npm",
      "args": ["start"],
      "cwd": "/path/to/jina-mcp-server",
      "env": {
        "JINA_API_KEY": "your_jina_api_key_here"
      }
    }
  }
}

Substitua /path/to/jina-mcp-server pelo seu diretório de instalação real (por exemplo, /Users/yourname/projects/jina-mcp-server ou /home/yourname/jina-mcp-server).

Em seguida, reinicie o Claude Desktop. As 9 ferramentas aparecerão no Claude.

Referência da API

Ferramenta: `primer`

Obter status do servidor e hora atual.

Parâmetros: Nenhum

Exemplo de Resposta:

Server Status: ✅ Online
Version: 1.0.0
Current Time: 11/9/2025, 5:45 PM
Timezone: America/New_York

Jina MCP Server is ready to serve requests.

Ferramenta: `read_url`

Ler e extrair conteúdo de texto de uma URL com opções avançadas de extração.

Parâmetros:

url (string, obrigatório): A URL a ser lida
timeout (número, opcional): Tempo limite da requisição em milissegundos (padrão: 30000)
locale (string, opcional): Localidade do navegador (ex.: "en-US", "pl-PL")
instruction (string, opcional): Instrução personalizada para extração de conteúdo
targetSelector (string, opcional): Seletor CSS para extrair elemento específico
removeSelector (string, opcional): Seletores CSS a remover (separados por vírgula)
waitForSelector (string, opcional): Seletor CSS para aguardar antes da extração
retainImages (string, opcional): Como lidar com imagens - "all", "none" ou "markdown" (padrão: "markdown")
retainLinks (string, opcional): Como lidar com links - "all", "none" ou "markdown" (padrão: "markdown")
withImagesSummary (booleano, opcional): Incluir resumo de imagens
withLinksSummary (booleano, opcional): Incluir resumo de links
proxy (string, opcional): URL do servidor proxy
userAgent (string, opcional): String User-Agent personalizada
jsonSchema (string, opcional): Esquema JSON para saída estruturada

Exemplo:

{
  "url": "https://example.com",
  "timeout": 30000,
  "locale": "en-US",
  "retainImages": "markdown",
  "retainLinks": "markdown"
}

Ferramenta: `capture_screenshot_url`

Capturar uma captura de tela de uma página web.

Parâmetros:

url (string, obrigatório): A URL para capturar
fullPage (booleano, opcional): Capturar página inteira (true) ou primeira tela (false, padrão)

Exemplo:

{
  "url": "https://example.com",
  "fullPage": true
}

Retorna: Dados de imagem codificados em Base64

Ferramenta: `guess_datetime_url`

Detectar a data de publicação de uma página web.

Parâmetros:

url (string, obrigatório): A URL a ser analisada

Retorna:

publication_date: Data detectada (ISO 8601)
accuracy: Nível de confiança (alto/médio/desconhecido)

Ferramenta: `parallel_read_url`

Ler múltiplas URLs simultaneamente com opções avançadas de extração.

Parâmetros:

urls (array de strings, obrigatório): URLs a serem lidas
maxParallel (número, opcional): Máximo de requisições concorrentes (1-10, padrão: 5)
timeout (número, opcional): Tempo limite da requisição em milissegundos (padrão: 30000)
locale (string, opcional): Localidade do navegador (ex.: "en-US", "pl-PL")
instruction (string, opcional): Instrução personalizada para extração de conteúdo
targetSelector (string, opcional): Seletor CSS para extrair elemento específico
retainImages (string, opcional): Como lidar com imagens - "all", "none" ou "markdown"
retainLinks (string, opcional): Como lidar com links - "all", "none" ou "markdown"

Exemplo:

{
  "urls": ["https://example1.com", "https://example2.com"],
  "maxParallel": 3,
  "retainImages": "markdown",
  "retainLinks": "markdown"
}

Ferramenta: `search_web`

Realizar uma busca web com opções avançadas de filtragem e localização.

Parâmetros:

query (string, obrigatório): Consulta de busca (ex.: "inteligência artificial")
count (número, opcional): Número de resultados a retornar (padrão: 10, máximo: 20)
location (string, opcional): Código do país para geolocalização (ex.: "US", "PL", "GB")
language (string, opcional): Código do idioma para resultados (ex.: "en", "pl", "de")
site (string, opcional): Filtrar resultados para domínio específico (ex.: "github.com")
page (número, opcional): Número da página para paginação (padrão: 1)
filetype (string, opcional): Filtrar por tipo de arquivo (ex.: "pdf", "doc", "xlsx")
intitle (string, opcional): Buscar apenas em títulos de páginas
timeout (número, opcional): Tempo limite da requisição em milissegundos (padrão: 30000)
provider (string, opcional): Provedor de busca ("google", "bing", etc.)

Exemplos:

{
  "query": "machine learning",
  "count": 10,
  "language": "en",
  "location": "US"
}

Busca com filtro de site:

{
  "query": "neural networks",
  "site": "github.com",
  "count": 5
}

Busca com filtro de tipo de arquivo:

{
  "query": "research paper",
  "filetype": "pdf",
  "language": "en",
  "count": 5
}

Ferramenta: `search_arxiv`

Buscar artigos acadêmicos no ArXiv.

Parâmetros:

query (string, obrigatório): Consulta de busca
maxResults (número, opcional): Máximo de artigos a retornar (padrão: 10)

Ferramenta: `search_images`

Buscar imagens.

Parâmetros:

query (string, obrigatório): Consulta de busca de imagens
count (número, opcional): Número de imagens (padrão: 20)

Ferramenta: `parallel_search_web`

Realizar múltiplas buscas web simultaneamente com opções avançadas de filtragem.

Parâmetros:

queries (array de strings, obrigatório): Consultas a buscar
maxParallel (número, opcional): Máximo de buscas concorrentes (1-10, padrão: 5)
count (número, opcional): Número de resultados por consulta (padrão: 10)
location (string, opcional): Código do país para geolocalização (ex.: "US", "PL")
language (string, opcional): Código do idioma para resultados (ex.: "en", "pl")
site (string, opcional): Filtrar resultados para domínio específico
page (número, opcional): Número da página para paginação
filetype (string, opcional): Filtrar por tipo de arquivo (ex.: "pdf")
intitle (string, opcional): Buscar apenas em títulos de páginas
timeout (número, opcional): Tempo limite da requisição em milissegundos
provider (string, opcional): Provedor de busca ("google", "bing", etc.)

Exemplo:

{
  "queries": ["Jina AI", "Claude AI", "Anthropic"],
  "maxParallel": 3,
  "language": "en",
  "count": 5
}

Operadores de Consulta de Busca

Use estes operadores no parâmetro query de search_web e parallel_search_web para filtrar resultados:

Operador	Exemplo	Finalidade
`site:`	`site:github.com machine learning`	Buscar apenas em domínio específico
`intitle:`	`intitle:"machine learning" tutorial`	Buscar apenas em títulos de páginas
`filetype:`	`machine learning filetype:pdf`	Filtrar por tipo de arquivo
`ext:`	`tutorial ext:docx`	Filtrar por extensão de arquivo

Exemplos

Buscar projetos Python no GitHub:

{
  "query": "site:github.com python projects",
  "count": 10
}

Encontrar artigos de pesquisa em PDF:

{
  "query": "deep learning filetype:pdf",
  "language": "en",
  "count": 5
}

Combinar múltiplos operadores:

{
  "query": "site:github.com intitle:tutorial python",
  "location": "US",
  "language": "en",
  "count": 10
}

Tratamento de Erros

Erros de Chave de API

Se a chave de API estiver ausente ou inválida, você verá:

🔑 Authentication Error: Invalid or missing API key.
Make sure your Jina API key is configured in .env

Limite de Taxa

Se o limite de taxa for excedido (500 RPM para titulares de chave de API):

⏱️ Rate Limit: Too many requests. Please wait and retry.

Erros de Rede

Erros de conexão e tempo limite são capturados e relatados com detalhes.

Estrutura do Projeto

mcp-server/
├── src/
│   ├── index.ts              # Main MCP server + tool handlers
│   ├── utils/
│   │   ├── api-client.ts      # Jina API client with error handling
│   │   ├── reader.ts          # Reader API functions (copied from test-jina-api)
│   │   ├── search.ts          # Search API functions (copied from test-jina-api)
│   │   ├── error-handler.ts   # MCP error formatting
│   │   └── yaml-formatter.ts  # Response formatting utility
│   └── types/
│       └── jina.ts            # TypeScript type definitions
├── dist/                      # Compiled JavaScript
├── package.json
├── tsconfig.json
├── .gitignore                  # Git ignore patterns
└── .env.example               # Example environment file (copy to .env to use)

Desenvolvimento

Build

npm run build

Executar

npm run dev

Limpar

npm run clean

Testes

Testar API Reader (Sem autenticação necessária)

curl https://r.jina.ai/https://example.com

Testar API Search (Requer autenticação)

curl -H "Authorization: Bearer YOUR_API_KEY" \
  "https://s.jina.ai/search?q=test"

Recursos e Capacidades

Recursos da API Reader

✅ Extração de conteúdo de qualquer URL
✅ Seletores CSS para extração direcionada
✅ Múltiplos formatos de saída (markdown, html, text)
✅ Controle de tratamento de imagens e links
✅ Suporte a User-Agent personalizado e proxy
✅ Leitura paralela de URLs (até 10 concorrentes)

Recursos da API Search

✅ Busca web com contagem de resultados até 20
✅ Filtragem por domínio (operador site:)
✅ Filtragem por título (operador intitle:)
✅ Filtragem por tipo de arquivo (operador filetype:)
✅ Localização geográfica (parâmetro gl)
✅ Filtragem por idioma (parâmetro hl)
✅ Suporte a paginação (parâmetro page)
✅ Busca paralela (até 10 concorrentes)
✅ Múltiplos provedores de busca (Google, Bing, etc.)

Limitações

API Reader: Nível gratuito (20 RPM sem chave, 500 RPM com chave)
API Search: Requer chave de API válida (limite de 500 RPM)
Resultados de busca: Máximo de 20 resultados por consulta
Operações paralelas: Máximo de 10 requisições concorrentes por lote
Dados de imagem: Retornados como string base64
Tempos limite: Máximo de 180 segundos por requisição

Limites de Taxa

API Reader: 20 RPM sem chave, 500 RPM com chave
API Search: 500 RPM com chave

Implemente lógica de backoff e repetição se os limites forem atingidos.

Solução de Problemas

"Extensão de arquivo desconhecida .ts"

Certifique-se de que você compilou o projeto:

npm run build

"Não é possível encontrar o módulo"

Reinstale as dependências:

rm -rf node_modules package-lock.json
npm install

O servidor não inicia

Verifique se o arquivo .env existe e tem um JINA_API_KEY válido:

cat .env

Ferramentas não aparecem no Claude

Reinicie o Claude Desktop
Verifique a sintaxe do JSON de configuração
Verifique se o caminho cwd está correto

Registro de Alterações

Versão 1.0.0 (Atual)

✅ 9 ferramentas MCP totalmente implementadas
✅ API Reader completa com extração avançada de conteúdo
✅ API Search completa com filtragem e paginação
✅ Parâmetros avançados de filtragem (site, idioma, tipo de arquivo, intitle, página, provedor)
✅ Parâmetros avançados de extração (localidade, instrução, seletores CSS, controle de imagem/link)
✅ Operações paralelas para leitura e busca (até 10 concorrentes)
✅ Tratamento abrangente de erros e registro de logs
✅ Documentação completa com exemplos e solução de problemas
✅ Código pronto para produção

O Que Está Incluído

✅ Recursos Prontos para Produção

9 Ferramentas MCP - Todas totalmente implementadas e testadas
API Reader - Extração de conteúdo com seletores CSS avançados, controle de imagem/link, suporte a localidade
API Search - Busca web, de imagens e ArXiv com filtragem e paginação
Operações Paralelas - Leitura e busca concorrentes de URLs (até 10 concorrentes)
Tratamento de Erros - Mensagens de erro abrangentes para erros de API, rede e validação
Suporte a Limite de Taxa - Lida com 500 RPM (com chave de API)
Configuração de Ambiente - Configuração fácil com variáveis de ambiente
Documentação Completa - Guia de início rápido, exemplos de configuração e solução de problemas

Benefícios de Desempenho

Redução de 50% no Consumo de Tokens - Esta implementação usa significativamente menos tokens do que implementações alternativas
Uso Eficiente da API - Tratamento otimizado de requisições e processamento de respostas
Tempos de Resposta Rápidos - Sobrecarga mínima na execução de ferramentas

Licença

MIT

Suporte

Para problemas com as APIs da Jina.AI, consulte: https://docs.jina.ai
Para a especificação do MCP, consulte: https://modelcontextprotocol.io

JinaAI

Documentação

Servidor MCP Jina

Versão 1.0.0

Documentação

Visão Geral

Ferramentas da API Reader (5)

Ferramentas da API Search (4)

Instalação e Início Rápido

Clonar e Instalar

Verificar a Instalação

Configuração

Definir Sua Chave de API

Uso

Teste Local com o MCP Inspector

Integração com Claude Desktop (Local)

Referência da API

Ferramenta: primer

Ferramenta: read_url

Ferramenta: capture_screenshot_url

Ferramenta: guess_datetime_url

Ferramenta: parallel_read_url

Ferramenta: search_web

Ferramenta: search_arxiv

Ferramenta: search_images

Ferramenta: parallel_search_web

Operadores de Consulta de Busca

Exemplos

Tratamento de Erros

Erros de Chave de API

Limite de Taxa

Erros de Rede

Estrutura do Projeto

Desenvolvimento

Build

Executar

Limpar

Testes

Testar API Reader (Sem autenticação necessária)

Testar API Search (Requer autenticação)

Recursos e Capacidades

Recursos da API Reader

Recursos da API Search

Limitações

Limites de Taxa

Solução de Problemas

"Extensão de arquivo desconhecida .ts"

"Não é possível encontrar o módulo"

O servidor não inicia

Ferramentas não aparecem no Claude

Registro de Alterações

Versão 1.0.0 (Atual)

O Que Está Incluído

✅ Recursos Prontos para Produção

Benefícios de Desempenho

Licença

Suporte

Ferramenta: `primer`

Ferramenta: `read_url`

Ferramenta: `capture_screenshot_url`

Ferramenta: `guess_datetime_url`

Ferramenta: `parallel_read_url`

Ferramenta: `search_web`

Ferramenta: `search_arxiv`

Ferramenta: `search_images`

Ferramenta: `parallel_search_web`