{
  "markdown": "# Academia MCP\n\n[![PyPI](https://img.shields.io/pypi/v/academia-mcp?label=PyPI%20package)](https://pypi.org/project/academia-mcp/)\n[![CI](https://github.com/IlyaGusev/academia_mcp/actions/workflows/python.yml/badge.svg)](https://github.com/IlyaGusev/academia_mcp/actions/workflows/python.yml)\n[![License](https://img.shields.io/github/license/IlyaGusev/academia_mcp)](LICENSE)\n[![smithery badge](https://smithery.ai/badge/@IlyaGusev/academia_mcp)](https://smithery.ai/server/@IlyaGusev/academia_mcp)\n[![Verified on MseeP](https://mseep.ai/badge.svg)](https://mseep.ai/app/e818878b-c3a6-4b3d-a5b4-e54dcd1f1fed)\n\nMCP server with tools to search, fetch, analyze, and report on scientific papers and datasets.\n\n### Features\n- ArXiv search and download\n- ACL Anthology search\n- Hugging Face datasets search\n- Semantic Scholar citations and references\n- Web search via Exa, Brave, or Tavily\n- Web page crawler, LaTeX compilation, PDF reading\n- Optional LLM-powered tools for document QA and research proposal workflows\n\n### Requirements\n- Python 3.12+\n\n### Install\n- Using pip (end users):\n```bash\npip3 install academia-mcp\n```\n\n- For development (uv + Makefile):\n```bash\nuv venv .venv\nmake install\n```\n\n### Quickstart\n- Run over HTTP (default transport):\n```bash\npython -m academia_mcp --transport streamable-http\n# OR\nuv run -m academia_mcp --transport streamable-http\n```\n\n- Run over stdio (for local MCP clients like Claude Desktop):\n```bash\npython -m academia_mcp --transport stdio\n# OR\nuv run -m academia_mcp --transport stdio\n```\n\nNotes:\n- Transports: `stdio`, `sse`, `streamable-http`.\n- `host`/`port` are used for HTTP transports; ignored for `stdio`. Default port is `5056` (or `PORT`).\n\n### Authentication\n\nAcademia MCP supports optional token-based authentication for HTTP transports (`streamable-http` and `sse`). Authentication is disabled by default to maintain backward compatibility.\n\n#### Enabling Authentication\n\nSet the `ENABLE_AUTH` environment variable to `true`:\n\n```bash\nexport ENABLE_AUTH=true\nexport TOKENS_FILE=/path/to/tokens.json  # Optional, defaults to ./tokens.json\n```\n\n#### Managing Tokens\n\nIssue a new token:\n```bash\nacademia_mcp auth issue-token --client-id=my-client --description=\"Production API client\"\n\n# Issue token with 30-day expiration\nacademia_mcp auth issue-token --client-id=test-client --expires-days=30\n\n# Issue token with custom scopes\nacademia_mcp auth issue-token --client-id=admin --scopes=\"read,write,admin\"\n```\n\nList active tokens:\n```bash\nacademia_mcp auth list-tokens\n```\n\nRevoke a token:\n```bash\nacademia_mcp auth revoke-token mcp_a1b2c3d4e5f6...\n```\n\n#### Using Tokens\n\nInclude the token in the `Authorization` header with the `Bearer` scheme or as a query parameter apiKey.\n\n**Security Notes:**\n- Tokens are displayed only once during issuance. Store them securely.\n- Use HTTPS in production to protect tokens in transit.\n- The `tokens.json` file is automatically created with restrictive permissions (mode 600).\n- Tokens are stored in plaintext (standard practice for bearer tokens) - protect the tokens file.\n\n### Claude Desktop config\n```json\n{\n  \"mcpServers\": {\n    \"academia\": {\n      \"command\": \"python3\",\n      \"args\": [\n        \"-m\",\n        \"academia_mcp\",\n        \"--transport\",\n        \"stdio\"\n      ]\n    }\n  }\n}\n```\n\n### Available tools (one-liners)\n- `arxiv_search`: Query arXiv with field-specific queries and filters.\n- `arxiv_download`: Fetch a paper by ID and convert to structured text (HTML/PDF modes).\n- `anthology_search`: Search ACL Anthology with fielded queries and optional date filtering.\n- `hf_datasets_search`: Find Hugging Face datasets with filters and sorting.\n- `s2_get_citations`: List papers citing a given arXiv paper (Semantic Scholar Graph).\n- `s2_get_references`: List papers referenced by a given arXiv paper.\n- `visit_webpage`: Fetch and normalize a web page.\n- `web_search`: Unified search wrapper; available when at least one of Exa/Brave/Tavily keys is set.\n- `exa_web_search`, `brave_web_search`, `tavily_web_search`: Provider-specific search.\n- `get_latex_templates_list`, `get_latex_template`: Enumerate and fetch built-in LaTeX templates.\n- `compile_latex`: Compile LaTeX to PDF in `WORKSPACE_DIR`.\n- `read_pdf`: Extract text per page from a PDF.\n- `download_pdf_paper`, `review_pdf_paper`: Download and optionally review PDFs (requires LLM + workspace).\n- `document_qa`: Answer questions over provided document chunks (requires LLM).\n- `extract_bitflip_info`, `generate_research_proposals`, `score_research_proposals`: Research proposal helpers (requires LLM).\n\nAvailability notes:\n- Set `WORKSPACE_DIR` to enable `compile_latex`, `read_pdf`, `download_pdf_paper`, and `review_pdf_paper`.\n- Set `OPENROUTER_API_KEY` to enable LLM tools (`document_qa`, `review_pdf_paper`, and bitflip tools).\n- Set one or more of `EXA_API_KEY`, `BRAVE_API_KEY`, `TAVILY_API_KEY` to enable `web_search` and provider tools.\n\n### Environment variables\nSet as needed, depending on which tools you use:\n\n- `OPENROUTER_API_KEY`: required for LLM-related tools.\n- `BASE_URL`: override OpenRouter base URL.\n- `DOCUMENT_QA_MODEL_NAME`: override default model for `document_qa`.\n- `BITFLIP_MODEL_NAME`: override default model for bitflip tools.\n- `TAVILY_API_KEY`: enables Tavily in `web_search`.\n- `EXA_API_KEY`: enables Exa in `web_search` and `visit_webpage`.\n- `BRAVE_API_KEY`: enables Brave in `web_search`.\n- `WORKSPACE_DIR`: directory for generated files (PDFs, temp artifacts).\n- `PORT`: HTTP port (default `5056`).\n\nYou can put these in a `.env` file in the project root.\n\n### Docker\nBuild the image:\n```bash\ndocker build -t academia_mcp .\n```\n\nRun the server (HTTP):\n```bash\ndocker run --rm -p 5056:5056 \\\n  -e PORT=5056 \\\n  -e OPENROUTER_API_KEY=your_key_here \\\n  -e WORKSPACE_DIR=/workspace \\\n  -v \"$PWD/workdir:/workspace\" \\\n  academia_mcp\n```\n\nOr use existing image: [`phoenix120/academia_mcp`](https://hub.docker.com/repository/docker/phoenix120/academia_mcp)\n\n### Examples\n- [Comprehensive report screencast (YouTube)](https://www.youtube.com/watch?v=4bweqQcN6w8)\n- [Single paper screencast (YouTube)](https://www.youtube.com/watch?v=IAAPMptJ5k8)\n\n### Makefile targets\n- `make install`: install the package in editable mode with uv\n- `make validate`: run black, flake8, and mypy (strict)\n- `make test`: run the test suite with pytest\n- `make publish`: build and publish using uv\n\n### LaTeX/PDF requirements\nOnly needed for LaTeX/PDF tools. Ensure a LaTeX distribution is installed and `pdflatex` is on PATH, as well as `latexmk`. On Debian/Ubuntu:\n```bash\nsudo apt install texlive-latex-base texlive-fonts-recommended texlive-latex-extra texlive-science latexmk\n```\n",
  "bytes": 6658,
  "sha": "e2890b1b1f5eae0f63b78216c9d1d972efd06dc10694bce599ca872cff0b472d",
  "repo_slug": "ilyagusev/academia_mcp",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_ai_smithery_ilyagusev_academia_mcp_100abcc7/readme"
}