File AI MCP server
✓ VerifiedProvides AI agents with structured document awareness by converting local files into searchable profiles, anchors, and contextual snippets.
Also known as flyfish-dev/file-ai, file-ai, @flyfish-dev/file-ai
- Stars
- 3
- Tools
- 5
- Downloads, 30 days
- 189
- Latest version
- 0.1.1
- Last commit
- Jun 24, 2026
- License
- Apache-2.0
What is File AI MCP?
File AI provides AI agents with structured document awareness by converting local files into searchable profiles, anchors, and contextual snippets. It exposes 5 tools, such as doc_analyze, doc_read, doc_search.
Summary generated from the project's README
About File AI MCP server
File AI provides AI agents with structured awareness of local documents by converting files into searchable profiles, anchors, and contextual snippets. It functions as a read-only layer that prevents agents from needing to reverse-engineer complex file internals like PDF, OOXML, or spreadsheets. Developers can run the server locally using npx or install it globally via npm to use the stdio transport. It also supports a streamable HTTP transport on a specified host and port.
The server uses Flyfish File Viewer core for format recognition across 206 registered extensions. It offers specific tools such as doc_analyze for parsing and caching indices, doc_read for accessing blocks or chunks, and doc_search for finding content with source anchors. It also includes doc_context for retrieving surrounding text and doc_list_formats to check supported extensions and renderer capabilities. While it provides deep extraction for text, code, Markdown, JSON, PDF, DOCX, XLSX, CSV, PPTX, and EML, it can also return metadata and warnings for other formats like CAD or media files.
Written from the project's README. Every use case is checked against a quote from it.
How to install File AI MCP
Formats verified 10 Nov 2026Add to CursorAdd to GooseInstall File AI MCP in Claude Code
$ claude mcp add file-ai -- npx -y @flyfish-dev/file-aiInstall File AI MCP in Cursor
~/.cursor/mcp.json
{
"mcpServers": {
"file-ai": {
"command": "npx",
"args": [
"-y",
"@flyfish-dev/file-ai"
]
}
}
}Install File AI MCP in VS Code
.vscode/mcp.json
{
"servers": {
"file-ai": {
"type": "stdio",
"command": "npx",
"args": [
"-y",
"@flyfish-dev/file-ai"
]
}
}
}Install File AI MCP in VS Code CLI
$ code --add-mcp '{"name":"file-ai","type":"stdio","command":"npx","args":["-y","@flyfish-dev/file-ai"]}'Install File AI MCP in Claude Desktop
claude_desktop_config.json
{
"mcpServers": {
"file-ai": {
"command": "npx",
"args": [
"-y",
"@flyfish-dev/file-ai"
]
}
}
}Install File AI MCP in Codex
$ codex mcp add file-ai -- npx -y @flyfish-dev/file-aiInstall File AI MCP in Codex config.toml
~/.codex/config.toml
[mcp_servers.file-ai] command = "npx" args = ["-y", "@flyfish-dev/file-ai"]
Install File AI MCP in Gemini CLI
$ gemini mcp add -s user file-ai npx -- -y @flyfish-dev/file-aiInstall File AI MCP in Gemini settings.json
~/.gemini/settings.json
{
"mcpServers": {
"file-ai": {
"command": "npx",
"args": [
"-y",
"@flyfish-dev/file-ai"
]
}
}
}File AI MCP tools 5
Detected from the READMEdoc_analyzedoc_readdoc_searchdoc_contextdoc_list_formats
| doc_analyze | — | |
| doc_read | — | |
| doc_search | — | |
| doc_context | — | |
| doc_list_formats | — |
Automated checks
Ran Nov 14, 2026Full report →Passed our automated checks. That is not a security audit: read the code and give the server the narrowest access it needs. How checks work
- Source repository linked and reachableflyfish-dev/file-ai is public and reachablegithub.com/flyfish-dev/file-ai ↗Pass
- Package names this repository as its source@flyfish-dev/file-ai names flyfish-dev/file-ai as sourcenpmjs.com/package/@flyfish-dev/file-ai ↗Pass
- Build provenance (Sigstore attestation)No build attestation published for this releaseNot checked
- Open source license (OSI)Apache-2.0spdx.org/licenses/Apache-2.0.html ↗Pass
- Commit or release in the last yearLast commit or release 2026-06-24github.com/flyfish-dev/file-ai ↗Pass
- OpenSSF ScorecardNot checked
- Package name not close to a popular packageNo popular package one edit away from @flyfish-dev/file-aiPass
- No critical advisory in the package or its dependencies154 resolved dependencies checked; no critical advisoryosv.dev ↗Pass
- No hidden instructions to the model5 tool descriptions and the README read; no override phrases, credential paths or hidden charactersPass
- Destructive tools are labelledNo tool named like delete, drop or execPass
- Remote endpoint answers the MCP handshakeNot checked
README
View on GitHubFile AI
Read-only document awareness MCP server for agents. File AI uses Flyfish File Viewer core as the source of truth for format recognition, then turns local files into a stable profile, anchors, blocks, chunks, outline, search results, and contextual snippets so an agent can understand document content without reverse-engineering PDF, OOXML, spreadsheet, email, or archive internals.
MCP Registry name: io.github.flyfish-dev/file-ai
Install
Use it directly with npx:
npx -y @flyfish-dev/file-ai
Or install it globally:
npm install -g @flyfish-dev/file-ai
file-ai --transport stdio
MCP Client Config
Stdio:
{
"mcpServers": {
"file-ai": {
"command": "npx",
"args": ["-y", "@flyfish-dev/file-ai"]
}
}
}
Streamable HTTP:
npx -y @flyfish-dev/file-ai --transport http --host 127.0.0.1 --port 8765
Endpoint:
http://127.0.0.1:8765/mcp
Tools
doc_analyze: parse a local file and cache a document index.doc_read: read blocks, chunks, or anchors from an existing index or path.doc_search: search cached content with source anchors.doc_context: retrieve nearby blocks around an anchor or query.doc_list_formats: list File Viewer core registry formats, all supported extensions, renderer capabilities, and File AI extractor coverage.
Resources
doc://{indexId}/profiledoc://{indexId}/outlinedoc://{indexId}/chunks
Supported Files
File AI recognizes formats through @file-viewer/core/headless, currently covering 206 registered extensions. profile.format is therefore aligned with the same renderer selection used by Flyfish File Viewer.
Content extraction is a separate layer. File AI provides structured awareness for text/code/Markdown/JSON, PDF text, DOCX, XLSX/CSV, PPTX, EML, and archive manifests. Other File Viewer renderer-only formats such as CAD, 3D, media, image, geospatial, drawing, ebook, and data assets are still recognized in profile.format; when no structured text extractor exists yet, File AI returns a profile plus best-effort metadata/text and explicit warnings in profile.warnings and profile.extraction.
Every content block carries an anchor such as a page, slide, worksheet, row range, nested path, or byte/text location. Agents should cite returned anchorId values when making document-grounded claims.
Development
pnpm install
pnpm build
pnpm test
pnpm validate:skill
Run locally:
pnpm dev -- --transport stdio
pnpm dev -- --transport http --port 8765
Publishing
The package includes:
- npm metadata for
@flyfish-dev/file-ai - MCP Registry metadata in
server.json - GitHub Actions workflow
.github/workflows/publish-mcp.yml
Release flow:
git tag v0.1.0
git push origin v0.1.0
The workflow publishes the npm package first, then publishes io.github.flyfish-dev/file-ai to the official MCP Registry through GitHub OIDC. The repository must have an NPM_TOKEN secret that can publish @flyfish-dev/file-ai.
The server is read-only. It does not mutate source documents.
File AI MCP questions
How do I add File AI MCP to Claude Code?
Run claude mcp add file-ai -- npx -y @flyfish-dev/file-ai in your terminal. Add --scope user to make it available in every project.
How do I add File AI MCP to Cursor?
Open ~/.cursor/mcp.json and add the server under mcpServers, using the Cursor config shown in the install section above.
What tools does File AI MCP provide?
It exposes 5 tools, including doc_analyze, doc_read, doc_search, doc_context, doc_list_formats.
Does File AI modify my local files?
No, the server is read-only and does not mutate your source documents.
What kind of file formats are supported?
It supports over 206 extensions, including text, code, Markdown, JSON, PDF, DOCX, XLSX/CSV, PPTX, EML, and archive manifests.